Documentation & API Clarifications for OpenHFT Posix

[peter-lawrey]

TL;DR

• Adds 161 + 86 new lines of docs (AGENTS.md, project-requirements.adoc, decision-log.adoc)
• Introduces package / enum / class-level Javadoc​ across the public API
• Formalises provider-fallback order and NoOpPosixAPI contract
• Cleans obsolete @since / boiler-plate comments and tightens wording
• Zero functional changes to runtime code – API surface is intact

Why?

1. Reduce onboarding friction – newcomers (human or AI) now have a single source of truth for build, style and contribution rules.
2. Prevent silent misbehaviour – clarified error-handling, MAP_FAILED, errno propagation and memory-locking caveats.
3. Establish traceability – every public constant now links back to the corresponding Linux man-page and POSIX-FN-* requirement.

What’s changed?

🗂️ New documentation

File	Purpose
AGENTS.md	House-rules for LLM agents & human contributors
src/main/adoc/project-requirements.adoc	Formal functional spec (POSIX-FN-001 … 012)

📖 Javadoc & comments

• Package-level package-info.java added to 11 packages.
• All enums (ClockId, OpenFlag, …) now carry concise, man-page-linked docs.
• Removed redundant boiler-plate setters/getters comments and @since tags.

⚙️ API clarifications (no behaviour change)

• PosixAPI
  • Explicitly documents provider order & thread-safety caveats.
  • Clarifies mmap return of -1 → MAP_FAILED.
  • Adds examples for mlock*, sched_*, etc.
• PosixRuntimeException now stores errno.
• NoOpPosixAPI contract spelt out (always lastError()==0).
• PosixAPIHolder renamed javadoc – still the same loader logic.

🧹 Code hygiene

• Dropped unused imports, misc spacing & ASCII-7 cleanup.
• Added README.adoc disclaimer: Audience = Internal, Stability = Volatile.

Backwards compatibility

• Binary/API compatible. No signatures changed, no new mandatory deps.
• Javadoc & comment removals do not affect runtime.
• The stricter ASCII-7 policy only affects future commits.

How to review

1. Docs first:
   • AGENTS.md & project-requirements.adoc – ensure guidelines match team consensus.
2. Public Javadoc: skim the new/updated blocks; look for inaccuracies or style nits.
3. Provider logic: verify PosixAPIHolder javadoc matches actual code path.
4. Run mvn -q verify – no tests touched, build should stay green.