Raise quality bar, tighten safety, and align docs/CI for Chronicle Compiler

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.
@@ -55,12 +55,13 @@ mvn -q verify
 
 ## Project requirements
 
-See the [Decision Log](src/main/adoc/decision-log.adoc) for the latest project decisions.
-See the [Project Requirements](src/main/adoc/project-requirements.adoc) for details on project requirements.
+See the [Decision Log](src/main/docs/decision-log.adoc) for the latest project decisions.
+See the [Project Requirements](src/main/docs/project-requirements.adoc) for details on project requirements.
 
 ## 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,14 +1,9 @@
-
 == Copyright 2016-2025 chronicle.software
 
-Licensed under the *Apache License, Version 2.0* (the "License");
-you may not use this file except in compliance with the License.
+Licensed under the *Apache License, Version 2.0* (the "License"); you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
 
     http://www.apache.org/licenses/LICENSE-2.0
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and limitations under the License.

README.adoc

@@ -2,6 +2,7 @@
 Chronicle Software
 :css-signature: demo
 :toc: macro
+:sectnums:
 :source-highlighter: rouge
 
 image:https://maven-badges.herokuapp.com/maven-central/net.openhft/compiler/badge.svg[]
@@ -11,11 +12,9 @@ image:https://sonarcloud.io/api/project_badges/measure?project=OpenHFT_Java-Runt
 
 toc::[]
 
-This library lets you feed _plain Java source as a_ `String`, compile it in-memory and
-immediately load the resulting `Class<?>` - perfect for hot-swapping logic while the JVM
-is still running.
+This library lets you feed _plain Java source as a_ `String`, compile it in-memory and immediately load the resulting `Class<?>` - perfect for hot-swapping logic while the JVM is still running.
 
-== 1 Quick-Start
+== Quick-Start
 
 [source,xml,subs=+quotes]
 ----
@@ -52,21 +51,22 @@ Class<?> clazz = CompilerUtils.CACHED_COMPILER.loadFromJava(className, src);
 ((Runnable) clazz.getDeclaredConstructor().newInstance()).run();
 ----
 
-== 2 Installation
+== Installation
 
-* Requires a **full JDK** (8, 11, 17 or 21 LTS), _not_ a slim JRE.
+* Requires a *full JDK* (8, 11, 17 or 21 LTS), _not_ a slim JRE.
 * On Java 11 + supply these flags (copy-paste safe):
 
 [source,bash]
 ----
 --add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
 --add-opens=jdk.compiler/com.sun.tools.javac=ALL-UNNAMED
 ----
+
 * Spring-Boot / fat-JAR users
 ** unpack Chronicle jars:
 `bootJar { requiresUnpack("**/chronicle-*.jar") }`
 
-== 3 Feature Highlights
+== Feature Highlights
 
 |===
 | Feature | Benefit
@@ -87,40 +87,43 @@ Class<?> clazz = CompilerUtils.CACHED_COMPILER.loadFromJava(className, src);
 | Build helper hierarchy in a single call
 |===
 
-== 4 Advanced Usage & Patterns
+== Advanced Usage & Patterns
 
-* Hot-swappable *strategy interface* for trading engines
+* Hot-swappable _strategy interface_ for trading engines
 ** Rule-engine: compile business rules implementing `Rule`
 *** Supports validator hook to vet user code
 ** Replace reflection: generate POJO accessors, 10 x faster
 ** Off-heap accessors with Chronicle Bytes / Map
 
-
-== 5 Operational Notes
+== Operational Notes
 
 * Compile on a background thread at start-up; then swap instances.
 ** Re-use class names _or_ child classloaders to control Metaspace.
 *** Use `CompilerUtils.DEBUGGING = true` during dev; remember to prune artefacts.
 ** SLF4J categories: `net.openhft.compiler` (INFO), compilation errors at ERROR.
 ** Micrometer timers/counters: `compiler.compiles`, `compiler.failures`.
 
-== 6 FAQ / Troubleshooting
+== Documentation & Requirements
+
+* link:src/main/docs/project-requirements.adoc[Project requirements] outline functional, non-functional, and compliance obligations.
+
+== FAQ / Troubleshooting
 
-* *`ToolProvider.getSystemJavaCompiler() == null`*
+* _`ToolProvider.getSystemJavaCompiler() == null`_
 * You are running on a JRE; use a JDK.
-* *`ClassNotFoundException: com.sun.tools.javac.api.JavacTool`*
+* _`ClassNotFoundException: com.sun.tools.javac.api.JavacTool`_
 * tools.jar is required on JDK <= 8. Newer JDKs need the `--add-exports` and `--add-opens` flags.
 * Classes never unload
 * Generate with a unique `ClassLoader` per version so classes can unload; each loader uses Metaspace.
 * Illegal-reflective-access warning
 * Add the `--add-opens` & `--add-exports` flags shown above.
 
-== 7 CI / Build & Test
+== CI / Build & Test
 
 * GitHub Actions workflow runs `mvn verify`, unit & race-condition tests.
 ** Code-coverage report published to SonarCloud badge above.
 
-== 8 Contributing & License
+== Contributing & License
 
 * Fork -> feature branch -> PR; run `mvn spotless:apply` before pushing.
-** All code under the *Apache License 2.0* - see `LICENSE`.
+** All code under the _Apache License 2.0_ - see `LICENSE`.