docs: describe the java-functional-style companion boundary

[martinfrancois]

Summary

• Problem: generic Java lambda and callback-style guidance now has its own package, martinfrancois/java-functional-style, and this repository needs to say where the boundary is.
• Why it matters: users should install both packages for stream cleanup that also involves non-trivial callbacks, and contributors should know which repository owns which guidance.
• What changed: README companion pointer, a short "Ownership Boundaries" section with the companion install command, a new docs/agents/ownership-boundaries.md that holds the only full ownership list, links from AGENTS.md, skill-behavior.md, and workflow.md, and the composition check description.
• What did not change: the runtime skill bundle. git diff v1.2.0 -- skills is empty, so the published 2.22x main score stays valid by construction. The earlier commits on this branch that rewrote SKILL.md and the references were reverted on the branch; they had only been proven in the composed setup, never standalone.

Change Type

• Skill behavior
• Evals or scoring
• Documentation
• CI, release, or dependency automation
• Repository metadata or contribution process
• Other maintenance

Linked Issue

• Related feat: Improve readability by avoiding multi-line lambdas #36 (lambdas as glue; now owned by the companion package)
• Related Add eval for Function.identity in toMap identity mappers #44 (Function.identity(); now owned by the companion package)
• Related feat(skill): add Java functional style package java-functional-style-skill#1

User-Visible Behavior

No runtime change. The README explains that java-streams owns stream and collector semantics, that java-functional-style owns general lambda and callback style, that each package works on its own, and that both should be installed together for stream cleanup with non-trivial callbacks.

Ownership Boundary

Kept in streams, unchanged: everything in the released SKILL.md, including the "lambdas as short glue" rule, because the published stream evals measure it.

Canonical in java-functional-style: identity functions, no-op functional stages, method-reference pitfalls, supplier laziness, checked-exception boundaries in callbacks, callback side effects. docs/agents/ownership-boundaries.md says not to grow that guidance here.

Merge Order

Merge after martinfrancois/java-functional-style is public on the Tessl registry (companion PR martinfrancois/java-functional-style-skill#1 first, then its "Make Public" flip). Until then the README's install command points at a package nobody can install.

Composition Check

The companion repository ships scripts/run_composed_eval.sh, which runs this repository's suites with both skills as context. Result for the current branch state:

main: 4/4 scenarios at 100% with-context, run 01a0c037-733f-742b-9b10-e62be368d466
      (streams 6826aca + functional-style d3fb985, Tessl default solver, 2026-09-20;
      the companion's skills/ and rules/ are unchanged since d3fb985, so the result
      describes the current pair)
      01-offer-availability-mapconcurrent 500/500, 02-delivery-appointments-mapconcurrent 400/400,
      03-payment-screening-gatherer-review 300/300, 04-invoice-bounds-and-temperature-windows 200/200

Reference and regression suites were not rerun in the composed setup: this PR changes no runtime text, and the ownership page requires the main suite for runtime changes and the broader suites when budget allows.

Validation

Checks most contributors can run:

• python3 scripts/validate_skill.py skills/java-streams -> passed
• python3 scripts/validate_eval_criteria.py evals evals-reference evals-regression -> passed, Validated 29 scenario(s): 11 natural, 18 explicit.
• python3 -m py_compile scripts/*.py -> passed
• bash -n scripts/*.sh -> passed
• python3 scripts/validate_json_files.py -> passed
• python3 scripts/validate_openai_agent_yaml.py -> passed
• tessl plugin lint . -> passed
• Manual rendered-doc review

Tessl-authenticated checks:

• Not needed for this docs-only change; the composition check above is tracked in the companion PR.

Human Verification

Reviewed the README wording and the agent docs; confirmed with git diff v1.2.0 -- skills that the runtime bundle is byte-identical to the released version.

Review Checklist

• The change is scoped to the sections, skill files, evals, or workflows described above. (It also names java-optionals as the third package of the set; that line is intentional.)
• Validation that applies to this change is checked above, or any unavailable check is explained.
• If Java stream guidance changed, Java baseline compatibility plus ordering, null handling, and parallelism were considered. (Not changed.)
• If evals or benchmark claims changed, the eval scenarios remain fair and do not leak answer keys, run IDs, or fixed score claims into runtime references. (Not changed.)
• If runtime skill text or references changed, hosted checks were widened as described in docs/agents/workflow.md, or any Tessl blocker is documented. (Not changed.)
• If a runtime skill/reference change was released, the final report includes the published main eval run plus post-change reference and regression run IDs, or a blocker issue for missing broad suites. (Not applicable.)
• Main and reference evals were run with both variants when hosted evals were needed; regression evals were run with context only unless reclassification back to reference was being checked. (Not needed.)
• New or moved eval scenarios follow the classifier recommendation, or the PR explains the maintainer-approved override. (None.)
• Every retained eval scenario has a 100% with-context result, or any below-100 result is documented as blocking follow-up rather than classified/reportable coverage. (Unchanged suite.)
• PR title or squash title uses Conventional Commits.
• Redaction checked: no tokens, private links, private eval artifacts, local host paths, or proprietary Java source.

AI Assistance (if used)

• AI-assisted PR
• I confirm I understand and reviewed the change

AI prompts / session logs (optional)

AI assistance was used to review the earlier branch state, restore the released runtime, draft the docs, and run a two-axis code review (standards and spec) whose findings were applied in the last commit. The diff and local validation were reviewed before updating this PR.