Add code-review profile, wire quality checks, and raise test coverage

AGENTS.md

@@ -8,23 +8,23 @@ LLM-based agents can accelerate development only if they respect our house rules
 
 ## Language & character-set policy
 
-| Requirement  | Rationale |
-|--------------|-----------|
-| **British English** spelling (`organisation`, `licence`, *not* `organization`, `license`) except technical US spellings like `synchronized` | Keeps wording consistent with Chronicle's London HQ and existing docs. See the University of Oxford style guide for reference. |
-| **ASCII-7 only** (code-points 0-127). Avoid smart quotes, non-breaking spaces and accented characters. | ASCII-7 survives every toolchain Chronicle uses, incl. low-latency binary wire formats that expect the 8th bit to be 0. |
-| If a symbol is not available in ASCII-7, use a textual form such as `micro-second`, `>=`, `:alpha:`, `:yes:`. This is the preferred approach and Unicode must not be inserted. | Extended or '8-bit ASCII' variants are *not* portable and are therefore disallowed. |
+| Requirement                                                                                                                                                                    | Rationale                                                                                                                      |
+|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
+| **British English** spelling (`organisation`, `licence`, *not* `organization`, `license`) except technical US spellings like `synchronized`                                    | Keeps wording consistent with Chronicle's London HQ and existing docs. See the University of Oxford style guide for reference. |
+| **ISO-8859-1** (code-points 0-255). Avoid smart quotes, non-breaking spaces and accented characters.                                                                         | ISO-8859-1 survives every toolchain Chronicle uses, incl. low-latency binary wire formats that expect the 8th bit to be 0.        |
+| If a symbol is not available in ISO-8859-1, use a textual form such as `micro-second`, `>=`, `:alpha:`, `:yes:`. This is the preferred approach and Unicode must not be inserted. | Extended or '8-bit ASCII' variants are *not* portable and are therefore disallowed.                                            |
 
 ## Javadoc guidelines
 
 **Goal:** Every Javadoc block should add information you cannot glean from the method signature alone. Anything else is
 noise and slows readers down.
 
-| Do | Don't |
-|----|-------|
-| State *behavioural contracts*, edge-cases, thread-safety guarantees, units, performance characteristics and checked exceptions. | Restate the obvious ("Gets the value", "Sets the name"). |
-| Keep the first sentence short; it becomes the summary line in aggregated docs. | Duplicate parameter names/ types unless more explanation is needed. |
-| Prefer `@param` for *constraints* and `@throws` for *conditions*, following Oracle's style guide. | Pad comments to reach a line-length target. |
-| Remove or rewrite autogenerated Javadoc for trivial getters/setters. | Leave stale comments that now contradict the code. |
+| Do                                                                                                                              | Don't                                                               |
+|---------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
+| State *behavioural contracts*, edge-cases, thread-safety guarantees, units, performance characteristics and checked exceptions. | Restate the obvious ("Gets the value", "Sets the name").            |
+| Keep the first sentence short; it becomes the summary line in aggregated docs.                                                  | Duplicate parameter names/ types unless more explanation is needed. |
+| Prefer `@param` for *constraints* and `@throws` for *conditions*, following Oracle's style guide.                               | Pad comments to reach a line-length target.                         |
+| Remove or rewrite autogenerated Javadoc for trivial getters/setters.                                                            | Leave stale comments that now contradict the code.                  |
 
 The principle that Javadoc should only explain what is *not* manifest from the signature is well-established in the
 wider Java community.
@@ -60,7 +60,8 @@ See the [Project Requirements](src/main/adoc/project-requirements.adoc) for deta
 
 ## Elevating the Workflow with Real-Time Documentation
 
-Building upon our existing Iterative Workflow, the newest recommendation is to emphasise *real-time updates* to documentation.
+Building upon our existing Iterative Workflow, the newest recommendation is to emphasise *real-time updates* to
+documentation.
 Ensure the relevant `.adoc` files are updated when features, requirements, implementation details, or tests change.
 This tight loop informs the AI accurately and creates immediate clarity for all team members.
 
@@ -75,41 +76,54 @@ This tight loop informs the AI accurately and creates immediate clarity for all
 
 ### Best Practices
 
-* **Maintain Sync**: Keep documentation (AsciiDoc), tests, and code synchronised in version control. Changes in one area should prompt reviews and potential updates in the others.
-* **Doc-First for New Work**: For *new* features or requirements, aim to update documentation first, then use AI to help produce or refine corresponding code and tests. For refactoring or initial bootstrapping, updates might flow from code/tests back to documentation, which should then be reviewed and finalised.
-* **Small Commits**: Each commit should ideally relate to a single requirement or coherent change, making reviews easier for humans and AI analysis tools.
-- **Team Buy-In**: Encourage everyone to review AI outputs critically and contribute to maintaining the synchronicity of all artefacts.
+* **Maintain Sync**: Keep documentation (AsciiDoc), tests, and code synchronised in version control. Changes in one area
+  should prompt reviews and potential updates in the others.
+* **Doc-First for New Work**: For *new* features or requirements, aim to update documentation first, then use AI to help
+  produce or refine corresponding code and tests. For refactoring or initial bootstrapping, updates might flow from
+  code/tests back to documentation, which should then be reviewed and finalised.
+* **Small Commits**: Each commit should ideally relate to a single requirement or coherent change, making reviews easier
+  for humans and AI analysis tools.
+
+- **Team Buy-In**: Encourage everyone to review AI outputs critically and contribute to maintaining the synchronicity of
+  all artefacts.
 
 ## AI Agent Guidelines
 
 When using AI agents to assist with development, please adhere to the following guidelines:
 
-* **Respect the Language & Character-set Policy**: Ensure all AI-generated content follows the British English and ASCII-7 guidelines outlined above.
-Focus on Clarity: AI-generated documentation should be clear and concise and add value beyond what is already present in the code or existing documentation.
-* **Avoid Redundancy**: Do not generate content that duplicates existing documentation or code comments unless it provides additional context or clarification.
-* **Review AI Outputs**: Always review AI-generated content for accuracy, relevance, and adherence to the project's documentation standards before committing it to the repository.
+* **Respect the Language & Character-set Policy**: Ensure all AI-generated content follows the British English and
+  ISO-8859-1 guidelines outlined above.
+  Focus on Clarity: AI-generated documentation should be clear and concise and add value beyond what is already present
+  in the code or existing documentation.
+* **Avoid Redundancy**: Do not generate content that duplicates existing documentation or code comments unless it
+  provides additional context or clarification.
+* **Review AI Outputs**: Always review AI-generated content for accuracy, relevance, and adherence to the project's
+  documentation standards before committing it to the repository.
 
 ## Company-Wide Tagging
 
-This section records **company-wide** decisions that apply to *all* Chronicle projects. All identifiers use the <Scope>-<Tag>-xxx prefix. The `xxx` are unique across in the same Scope even if the tags are different. Component-specific decisions live in their xxx-decision-log.adoc files.
+This section records **company-wide** decisions that apply to *all* Chronicle projects. All identifiers use
+the <Scope>-<Tag>-xxx prefix. The `xxx` are unique across in the same Scope even if the tags are different.
+Component-specific decisions live in their xxx-decision-log.adoc files.
 
 ### Tag Taxonomy (Nine-Box Framework)
 
-To improve traceability, we adopt the Nine-Box taxonomy for requirement and decision identifiers. These tags are used in addition to the existing ALL prefix, which remains reserved for global decisions across every project.
+To improve traceability, we adopt the Nine-Box taxonomy for requirement and decision identifiers. These tags are used in
+addition to the existing ALL prefix, which remains reserved for global decisions across every project.
 
 .Adopt a Nine-Box Requirement Taxonomy
 
-|Tag | Scope | Typical examples |
-|----|-------|------------------|
-|FN |Functional user-visible behaviour | Message routing, business rules |
-|NF-P |Non-functional - Performance | Latency budgets, throughput targets |
-|NF-S |Non-functional - Security | Authentication method, TLS version |
-|NF-O |Non-functional - Operability | Logging, monitoring, health checks |
-|TEST |Test / QA obligations | Chaos scenarios, benchmarking rigs |
-|DOC |Documentation obligations | Sequence diagrams, user guides |
-|OPS |Operational / DevOps concerns | Helm values, deployment checklist |
-|UX |Operator or end-user experience | CLI ergonomics, dashboard layouts |
-|RISK |Compliance / risk controls | GDPR retention, audit trail |
+| Tag  | Scope                             | Typical examples                    |
+|------|-----------------------------------|-------------------------------------|
+| FN   | Functional user-visible behaviour | Message routing, business rules     |
+| NF-P | Non-functional - Performance      | Latency budgets, throughput targets |
+| NF-S | Non-functional - Security         | Authentication method, TLS version  |
+| NF-O | Non-functional - Operability      | Logging, monitoring, health checks  |
+| TEST | Test / QA obligations             | Chaos scenarios, benchmarking rigs  |
+| DOC  | Documentation obligations         | Sequence diagrams, user guides      |
+| OPS  | Operational / DevOps concerns     | Helm values, deployment checklist   |
+| UX   | Operator or end-user experience   | CLI ergonomics, dashboard layouts   |
+| RISK | Compliance / risk controls        | GDPR retention, audit trail         |
 
 `ALL-*` stays global, case-exact tags. Pick one primary tag if multiple apply.
 

LICENSE.adoc

@@ -1,3 +1,8 @@
+= Posix Module License
+:sectnums:
+:encoding: ISO-8859-1
+:lang: en-GB
+
 == Copyright 2016 higherfrequencytrading.com
 
 Licensed under the *Apache License, Version 2.0* (the "License"); you may not use this file except in compliance with the License.

README.adoc

@@ -1,13 +1,14 @@
 = Posix
 Peter Lawrey, 31/08/2021
 :toc:
+:sectnums:
 :icons: font
 :encoding: ISO-8859-1
 :lang: en-GB
 :source-highlighter: rouge
 
 [abstract]
-The _OpenHFT Posix_ module is a zero-GC, low-latency Java façade over a **portable subset of POSIX/Linux system calls**, with provider fall-back to JNR, JNA or raw/reflective variants.
+The _OpenHFT Posix_ module is a zero-GC, low-latency Java façade over a *portable subset of POSIX/Linux system calls*, with provider fall-back to JNR, JNA or raw/reflective variants.
 Chronicle components rely on it for deterministic file-IO, memory-mapping and CPU-affinity operations that the JDK does not expose.
 
 Audience: Internal, Stability: Stable
@@ -50,14 +51,14 @@ posix.munmap(addr, 4096);
 |===
 | Provider | Native layer | Typical when…
 
-| `JNRPosixAPI`      | JNR-FFI      | **Linux** & x86_64/ARM, fastest syscalls
-| `WinJNRPosixAPI`   | JNR-FFI      | **Windows** equivalents (subset)
+| `JNRPosixAPI`      | JNR-FFI      | *Linux* & x86_64/ARM, fastest syscalls
+| `WinJNRPosixAPI`   | JNR-FFI      | *Windows* equivalents (subset)
 | `JNAPosixAPI`      | JNA          | exotic/legacy platforms
 | `RawPosixAPI`      | Reflection   | JVM ≥ 21 with `--add-opens`
 | `NoOpPosixAPI`     | —            | CI sandboxes / Graal native-image
 |===
 
-`-Dchronicle.posix.provider=` *provider-name* overrides the auto-choice.
+`-Dchronicle.posix.provider=` _provider-name_ overrides the auto-choice.
 
 == Supported system calls
 
@@ -74,7 +75,7 @@ posix.munmap(addr, 4096);
 | addr / 0        | `MAP_FAILED` → -1 sentinel
 
 | CPU-affinity
-| `sched_*affinity*`, helpers `sched_setaffinity_as` …
+| `sched__affinity_`, helpers `sched_setaffinity_as` …
 | 0               | portable bit-mask helpers
 
 | Timing
@@ -92,7 +93,7 @@ mvn -q verify
 
 Environment variables:
 
-* `POSIX_TEST_ALLOW_NATIVE` – set to *false* in CI to force `NoOpPosixAPI`.
+* `POSIX_TEST_ALLOW_NATIVE` – set to _false_ in CI to force `NoOpPosixAPI`.
 * `POSIX_SYSLOG_LEVEL` – adjust logging noise during native provider load.
 
 == Troubleshooting
@@ -117,10 +118,8 @@ Add JVM arg:
 ====
 
 [%collapsible]
-
 == Further reading
 
 * link:src/main/adoc/project-requirements.adoc[Functional requirements]
 * link:src/main/adoc/decision-log.adoc[Architecture decision log]
 * link:https://man7.org/linux/man-pages/[Linux man-pages]
-