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 Optional 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, readme.md, workflow.md, and CONTRIBUTING.md, and the composition check description.
• What did not change: the runtime skill bundle. git diff v1.0.0 -- skills is empty, so the published 2.08x main score stays valid by construction.

Change Type

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

Linked Issue

• Related feat(skill): add Java functional style package java-functional-style-skill#1

User-Visible Behavior

No runtime change. The README explains that java-optionals owns Optional 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 Optional cleanup with non-trivial callbacks.

Ownership Boundary

Kept in optionals, unchanged: everything in the released SKILL.md, including the lazy-fallback rule, because the published Optional 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 across two runs (3 + 1)
      run 01a0c037-8b98-70cb-a114-2eb9911ea75c: 10-first-pass-retry-backoff 100/100,
      11-checked-boundary-selection-cleanup 60/60, 50-command-sanitizer-feature 100/100
      (04 hit a sandbox failure with no output in that run)
      run 01a0c045-04f9-72f3-956e-f30dd5fb9381: 04-frontmatter-port-feature 100/100
      (optionals 14cb014 + 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)

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-optionals -> passed
• python3 scripts/validate_eval_criteria.py evals evals-reference evals-regression -> passed, Validated 52 scenario(s): 4 natural, 48 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.0.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-streams 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 Optional guidance changed, Java baseline compatibility plus present, absent, and fallback behavior 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, 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.