From 89bb4512f10d89ce795e8f4577f9b1df0146d49b Mon Sep 17 00:00:00 2001 From: martinfrancois Date: Mon, 21 Sep 2026 05:02:14 +0200 Subject: [PATCH] docs: describe the java-functional-style companion boundary General lambda and callback style now lives in the companion package martinfrancois/java-functional-style. This repository keeps its released runtime bundle byte-identical to v1.2.0 (git diff v1.2.0 -- skills is empty), so the published main score holds by construction, and documents the boundary instead: - README: one paragraph on the companion plus its install command; the full ownership list lives in docs/agents/ownership-boundaries.md. - docs/agents/ownership-boundaries.md: the only ownership list, the rule that each package works on its own, and the composition check that runs this repository's evals with both skills as context (runner in the companion repository; main suite 4/4 at 100% with-context in run 01a0c037-733f-742b-9b10-e62be368d466). - AGENTS.md, skill-behavior.md, workflow.md: links and one sentence each pointing at that page. --- AGENTS.md | 1 + README.md | 21 +++++++++++++ docs/agents/ownership-boundaries.md | 47 +++++++++++++++++++++++++++++ docs/agents/skill-behavior.md | 3 ++ docs/agents/workflow.md | 3 ++ 5 files changed, 75 insertions(+) create mode 100644 docs/agents/ownership-boundaries.md diff --git a/AGENTS.md b/AGENTS.md index 8d580c3..a847f2a 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 76ab089..a61b390 100644 --- a/README.md +++ b/README.md @@ -18,12 +18,16 @@ as a design choice rather than a default optimization. It also tells the agent to check the project Java version first. The right stream code for Java 8 may be different from the right code for Java 17, Java 21, or Java 24. +General lambda and callback style lives in the companion package +`martinfrancois/java-functional-style`; see [Ownership Boundaries](#ownership-boundaries). + ## Contents - [Getting Started](#getting-started) - [Why This Exists](#why-this-exists) - [Common Stream Mistakes](#common-stream-mistakes) - [What It Helps With](#what-it-helps-with) +- [Ownership Boundaries](#ownership-boundaries) - [How It's Evaluated](#how-its-evaluated) - [Origin](#origin) - [Contributing](#contributing) @@ -241,6 +245,23 @@ Poor fit: - large API redesigns or new dependencies without maintainer agreement; - changing business behavior just to make code look more functional. +## Ownership Boundaries + +`martinfrancois/java-streams` owns stream and collector semantics. General lambda and callback +style (identity functions, no-op stages, helper extraction, comparator composition, +method-reference pitfalls, supplier laziness, checked boundaries in callbacks) is owned by the +companion package `martinfrancois/java-functional-style` +([repository](https://github.com/martinfrancois/java-functional-style-skill)), and Optional +semantics by `martinfrancois/java-optionals` +([repository](https://github.com/martinfrancois/java-optionals-skill)). + +Each package works on its own. Install the companion next to this one when stream cleanup also +involves non-trivial callbacks: + +```bash +npx tessl i martinfrancois/java-functional-style +``` + ## How It's Evaluated The skill is tested on Java stream implementation, review, and cleanup tasks. Each task is run diff --git a/docs/agents/ownership-boundaries.md b/docs/agents/ownership-boundaries.md new file mode 100644 index 0000000..19de8df --- /dev/null +++ b/docs/agents/ownership-boundaries.md @@ -0,0 +1,47 @@ +# Ownership Boundaries + +## Scope + +Use this when changing runtime guidance, README wording, evals, or companion-package documentation +for Java Streams. This page holds the only full list of who owns what; other pages link here. + +## Rules + +- `java-streams` owns stream and collector semantics: terminal operation choice, collector choice, + duplicate-key and null behavior, encounter order, primitive streams, `findFirst` versus + `findAny`, `parallelStream`, `Gatherers.mapConcurrent`, stream Java-version compatibility, and + stream-specific behavior preservation. It also keeps its own short "lambdas as glue" rule and its + preference for method references, because the published stream evals measure them. +- `martinfrancois/java-functional-style` owns general Java lambda and functional-interface style: + identity functions, no-op functional stages, helper extraction from block callbacks, comparator + composition, method-reference pitfalls (receiver binding, overloads, boxing), supplier laziness, + checked-exception boundaries inside callbacks, and callback side-effect boundaries. +- `martinfrancois/java-optionals` owns Optional semantics. +- Each package works on its own. Don't make stream guidance depend on the companion being installed, + and don't remove stream guidance because the companion also covers it. +- Don't grow generic lambda guidance here. When a functional-style gap shows up in stream work, fix + it in the companion and add stream-side text only if hosted evidence proves the stream evals need + it. + +## Composition Check + +Adding the companion must not make this skill worse. The check runs this repository's evals, +unchanged, with both skills injected as context and requires 100% with-context for every scenario +in the run: + +```bash +# from a checkout of java-functional-style-skill, next to this repository +scripts/run_composed_eval.sh ../java-streams-skill main +``` + +The main suite is required whenever either package changes runtime text; run `reference` and +`regression` too when the change touches review wording or when budget allows. The companion +repository owns the runner and runs the check before its releases; this repository runs it when +its own runtime changes. Local validation alone doesn't satisfy this check. + +## References + +- [Skill Behavior](skill-behavior.md) +- [README Guidance](readme.md) +- [Eval Guidance](evals.md) +- [Workflow](workflow.md) diff --git a/docs/agents/skill-behavior.md b/docs/agents/skill-behavior.md index 7a101f7..6d33be0 100644 --- a/docs/agents/skill-behavior.md +++ b/docs/agents/skill-behavior.md @@ -42,6 +42,8 @@ guidance, or auto-selection wording. - Keep stream lambdas as short glue. Prefer method references or one-expression lambdas whose body stays on the same line as `->`, and extract named helpers for branching, loops, temporary variables, formatting, merge rules, or nested stream chains that would continue on later lines. + This rule stays here because the published stream evals measure it; deeper callback-style + guidance belongs to the companion package, see [Ownership Boundaries](ownership-boundaries.md). - Runtime guidance should keep internal workflow language out of ordinary user-facing reviews. Avoid terms such as "hard stop", "marker", "scan", "checklist", and skill names unless the user asked for an explicit skill workflow, audit, or scan command. @@ -52,3 +54,4 @@ guidance, or auto-selection wording. - [README Guidance](readme.md) - [Eval Guidance](evals.md) +- [Ownership Boundaries](ownership-boundaries.md) diff --git a/docs/agents/workflow.md b/docs/agents/workflow.md index fb6bd9e..76929e1 100644 --- a/docs/agents/workflow.md +++ b/docs/agents/workflow.md @@ -126,6 +126,9 @@ release-readiness. Follow the recommendation unless the pull request documents a maintainer-approved override. +- When runtime skill text changes, also run the composition check in + [Ownership Boundaries](ownership-boundaries.md) so the companion package still composes cleanly. + - Run the Tessl skill quality review at threshold 100 when changing runtime skill content: ```bash