Harden Java runtime compiler caching, I/O safety, and documentation/agent guidance

AGENTS.md

@@ -1,5 +1,12 @@
 # Guidance for AI agents, bots, and humans contributing to Chronicle Software's OpenHFT projects.
 
+- Follow repository `AGENTS.md` for the base rules; this file adds Java-Runtime-Compiler specifics. Durable docs live in `src/main/docs/` with the landing page at `README.adoc`.
+- Purpose: compile plain Java source strings at runtime and load classes; used for dynamic logic injection and code generation pipelines.
+- Build commands: full build `mvn -q clean verify`; module-only without tests `mvn -pl Java-Runtime-Compiler -am -DskipTests install`.
+- Quality gates: keep Checkstyle/SpotBugs clean; avoid unsafe classloader leaks; ensure generated classes are closed/evicted as documented.
+- Documentation: maintain Nine-Box IDs in `src/main/docs/project-requirements.adoc` and link decisions/tests to them; British English and ASCII/ISO-8859-1 with `:source-highlighter: rouge`.
+- Guardrails: treat generated code as untrusted; enforce validation and sandboxing controls described in `src/main/docs/ai-runtime-guardrails.adoc` / `ai-validator-spec.adoc`; call out any security-impacting configuration changes.
+
 LLM-based agents can accelerate development only if they respect our house rules. This file tells you:
 
 * how to run and verify the build;
@@ -10,41 +17,68 @@ LLM-based agents can accelerate development only if they respect our house rules
 
 | 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. |
+| **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](https://www.ox.ac.uk/public-affairs/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. |
+| If a symbol is not available in ISO-8859-1, use a textual form such as `>=`, `: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. |
+| Tools to check ASCII compliance include `iconv -f ascii -t ascii` and IDE settings that flag non-ASCII characters. | These help catch stray Unicode characters before code review. |
 
 ## 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 |
+| 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. |
+| 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.
+The principle that Javadoc should only explain what is *not* manifest from the
+signature is well-established in the wider Java community.
+
+Inline comments should also avoid noise. The following example shows the
+difference:
+
+```java
+// BAD: adds no value
+int count; // the count
+
+// GOOD: explains a subtlety
+// count of messages pending flush
+int count;
+```
 
 ## Build & test commands
 
-Agents must verify that the project still compiles and all unit tests pass before opening a PR:
+Agents must verify that the project still compiles and all unit tests pass before opening a PR. Running from a clean checkout avoids stale artifacts:
 
 ```bash
 # From repo root
-mvn -q verify
+mvn -q clean verify
 ```
+The command should exit with code `0` to indicate success.
+
+### Quality profiles
+
+When running static analysis and coverage, prefer the shared Chronicle profiles:
+
+- From the root aggregator (all modules): `mvn -P quality clean verify` for Checkstyle and SpotBugs, and `mvn -P sonar clean verify` for JaCoCo and SonarCloud integration.
 
 ## Commit-message & PR etiquette
 
-1. **Subject line <= 72 chars**, imperative mood: "Fix roll-cycle offset in `ExcerptAppender`".
+1. **Subject line <= 72 chars**, imperative mood: Fix roll-cycle offset in `ExcerptAppender`.
 2. Reference the JIRA/GitHub issue if it exists.
 3. In *body*: *root cause -> fix -> measurable impact* (latency, allocation, etc.). Use ASCII bullet points.
 4. **Run `mvn verify`** again after rebasing.
 
+### When to open a PR
+
+* Open a pull request once your branch builds and tests pass with `mvn -q clean verify`.
+* Link the PR to the relevant issue or decision record.
+* Keep PRs focused: avoid bundling unrelated refactoring with new features.
+* Re-run the build after addressing review comments to ensure nothing broke.
+
 ## What to ask the reviewers
 
 * *Is this AsciiDoc documentation precise enough for a clean-room re-implementation?*
@@ -53,10 +87,18 @@ mvn -q verify
 * Does the commit point back to the relevant requirement or decision tag?
 * Would an example or small diagram help future maintainers?
 
+### Security checklist (review **after every change**)
+
+**Run a security review on *every* PR**: Walk through the diff looking for input validation, authentication, authorisation, encoding/escaping, overflow, resource exhaustion and timing-attack issues.
+
+**Never commit secrets or credentials**: tokens, passwords, private keys, TLS materials, internal hostnames, Use environment variables, HashiCorp Vault, AWS/GCP Secret Manager, etc.
+
+**Document security trade-offs**: Chronicle prioritises low-latency systems; sometimes we relax safety checks for specific reasons. Future maintainers must find these hot-spots quickly, In Javadoc and `.adoc` files call out *why* e.g. "Unchecked cast for performance - assumes trusted input".
+
 ## 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
 
@@ -84,7 +126,7 @@ This tight loop informs the AI accurately and creates immediate clarity for all
 
 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.
+* **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.
@@ -118,13 +160,12 @@ To improve traceability, we adopt the Nine-Box taxonomy for requirement and deci
 ```asciidoc
 === [Identifier] Title of Decision
 
-- Date: YYYY-MM-DD
-- Context:
+Date :: YYYY-MM-DD
+Context ::
 * What is the issue that this decision addresses?
 * What are the driving forces, constraints, and requirements?
-- Decision Statement:
-* What is the change that is being proposed or was decided?
-- **Alternatives Considered:**
+Decision Statement :: What is the change that is being proposed or was decided?
+Alternatives Considered ::
 * [Alternative 1 Name/Type]:
 ** *Description:* Brief description of the alternative.
 ** *Pros:* ...
@@ -133,14 +174,14 @@ To improve traceability, we adopt the Nine-Box taxonomy for requirement and deci
 ** *Description:* Brief description of the alternative.
 ** *Pros:* ...
 ** *Cons:* ...
-- **Rationale for Decision:**
+Rationale for Decision ::
 * Why was the chosen decision selected?
 * How does it address the context and outweigh the cons of alternatives?
-- **Impact & Consequences:**
+Impact & Consequences ::
 * What are the positive and negative consequences of this decision?
 * How does this decision affect the system, developers, users, or operations?
 - What are the trade-offs made?
-- **Notes/Links:**
+Notes/Links ::
 ** (Optional: Links to relevant issues, discussions, documentation, proof-of-concepts)
 ```
 
@@ -151,11 +192,31 @@ To improve traceability, we adopt the Nine-Box taxonomy for requirement and deci
 Do not rely on indentation for list items in AsciiDoc documents. Use the following pattern instead:
 
 ```asciidoc
-- top level
-* second level
-  ** third level
+section :: Top Level Section (Optional)
+* first level
+  ** nested level
 ```
 
 ### Emphasis and Bold Text
 
-In AsciiDoc, an underscore `_` is _emphasis_; `*text*` is *bold*.
+In AsciiDoc, an underscore `_` is _emphasis_; `*text*` is *bold*.
+
+### Section Numbering
+
+Use automatic section numbering for all `.adoc` files.
+
+* Add `:sectnums:` to the document header.
+* Do not prefix section titles with manual numbers to avoid duplication.
+
+```asciidoc
+= Document Title
+Chronicle Software
+:toc:
+:sectnums:
+:lang: en-GB
+:source-highlighter: rouge
+
+The document overview goes here.
+
+== Section 1 Title
+```

LICENSE.adoc

@@ -1,5 +1,8 @@
 
 == Copyright 2016-2025 chronicle.software
+:toc:
+:lang: en-GB
+:source-highlighter: rouge
 
 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,8 +1,13 @@
 = Chronicle Runtime Compiler
+:toc:
+:lang: en-GB
+:source-highlighter: rouge
 Chronicle Software
-:css-signature: demo
-:toc: macro
+:toc:
 :sectnums:
+:toc: macro
+:lang: en-GB
+:css-signature: demo
 :source-highlighter: rouge
 
 image:https://maven-badges.herokuapp.com/maven-central/net.openhft/compiler/badge.svg[]