refactor(skill): document functional style companion boundary

[martinfrancois]

Summary

• Problem: java-optionals needed a clear ownership boundary with the new cross-cutting Java functional-style package.
• Why it matters: Optional semantic guidance should remain in this package while callback readability, identity functions, and no-op functional stages are owned by java-functional-style.
• What changed: updated docs to explain the companion relationship and ownership boundary.
• What did not change: Optional runtime skill text, references, eval tasks, and eval criteria were not changed.

Change Type

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

Linked Issue

• Related martinfrancois/java-functional-style-skill#1

User-Visible Behavior

Contributors and users can now see that java-optionals owns Optional semantics while martinfrancois/java-functional-style owns general lambda/callback readability, identity functions, no-op functional stages, supplier/callback style, and side-effect boundaries.

Bug Fix Details

• Root cause: the new companion package introduced an ownership boundary that optionals docs did not previously describe.
• Test, eval, or guardrail added: local validation and Tessl quality review were run. Hosted Optional composition evals were not required because this PR does not change Optional runtime guidance, references, eval tasks, or eval criteria.
• If no test or eval was added, why not: docs-only boundary update; no Optional behavior was changed.

Ownership Boundary

java-optionals owns Optional semantics: absence and fallback behavior, Optional API choice, fallback laziness as Optional semantics, checked IO/parser/prompt boundaries, Java-version compatibility, and present/absent/exception contract preservation.

java-functional-style owns general Java lambda and functional-interface style: method references, identity functions, no-op functional stages, callback extraction, supplier laziness as general callback style, and callback side-effect guidance.

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 or example review, if docs or examples changed

Tessl-authenticated checks:

• bash scripts/check_publish_dry_run.sh . -> not run; no publish-related change
• tessl plugin publish --dry-run --bump patch . -> not run; no publish-related change
• tessl skill review --threshold 100 skills/java-optionals/SKILL.md / equivalent quality review -> 100, run 019f0f80-6ab4-775d-a973-0ab001271473
• Hosted Optional composition evals -> not required; Optional runtime guidance, references, eval tasks, and eval criteria were unchanged.

Details:

No Optional behavior changed. The mandatory Optional composition gate applies when Optional runtime guidance or evals are changed; this PR only documents the companion boundary.

Human Verification

Reviewed the docs to confirm they describe `java-optionals` as the Optional semantics owner and `java-functional-style` as the callback/functional-style owner without adding new Optional runtime guidance.

Review Checklist

• The change is scoped to the sections, skill files, evals, or workflows described above.
• Validation that applies to this change is checked above, or any unavailable check is explained.
• If Java Optional guidance changed, Java baseline compatibility, fallback timing, null interop, primitive Optionals, and checked boundaries were considered.
• 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.
• If runtime skill text or references changed, hosted checks were widened from targeted affected scenarios to main/reference/regression as described in docs/agents/workflow.md, or any Tessl blocker is documented.
• 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.
• 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.
• New or moved eval scenarios follow the classifier recommendation, or the PR explains the maintainer-approved override.
• 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.
• 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 draft and edit the docs and run validation. The submitted diff and validation results were reviewed before opening this PR.