diff --git a/AGENTS.md b/AGENTS.md index 4231165..9d94747 100644 --- a/AGENTS.md +++ b/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) diff --git a/README.md b/README.md index 0442dfb..5678068 100644 --- a/README.md +++ b/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: diff --git a/docs/agents/ownership-boundaries.md b/docs/agents/ownership-boundaries.md new file mode 100644 index 0000000..010c1b8 --- /dev/null +++ b/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) diff --git a/docs/agents/readme.md b/docs/agents/readme.md index b35b67d..deab83d 100644 --- a/docs/agents/readme.md +++ b/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 diff --git a/docs/agents/skill-behavior.md b/docs/agents/skill-behavior.md index 068122b..5e13e35 100644 --- a/docs/agents/skill-behavior.md +++ b/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)