Clarify Chronicle Threads requirements/docs and tighten event loop, pauser, and disk-monitor behaviour

AGENTS.md

@@ -10,9 +10,10 @@ 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
 
@@ -26,12 +27,24 @@ noise and slows readers down.
 | 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
@@ -40,11 +53,18 @@ mvn -q verify
 
 ## 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 +73,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 +112,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.
@@ -122,8 +150,7 @@ 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?
+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.
@@ -151,11 +178,31 @@ Notes/Links::
 Do not rely on indentation for list items in AsciiDoc documents. Use the following pattern instead:
 
 ```asciidoc
-section:: Top Level Section
+section :: Top Level Section (Optional)
 * first level
   ** nested level
 ```
 
 ### Emphasis and Bold Text
 
 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,4 +1,3 @@
-
 == Copyright 2016-2025 chronicle.software
 
 Licensed under the *Apache License, Version 2.0* (the "License");

README.adoc

@@ -1,9 +1,11 @@
 = Chronicle Threads
 Chronicle Software
-:css-signature: demo
 :toc: macro
-:toclevels: 2
 :icons: font
+:lang: en-GB
+:toclevels: 2
+:css-signature: demo
+:source-highlighter: rouge
 
 image:https://maven-badges.herokuapp.com/maven-central/net.openhft/chronicle-threads/badge.svg[caption="",link=https://maven-badges.herokuapp.com/maven-central/net.openhft/chronicle-threads]
 image:https://javadoc.io/badge2/net.openhft/chronicle-threads/javadoc.svg[link="https://www.javadoc.io/doc/net.openhft/chronicle-threads/latest/index.html"]
@@ -79,6 +81,19 @@ public final class ExampleEventHandler implements EventHandler {
 
 call the `addHandler` method of the event loop, see also <<Start event loop>>
 
+== Links
+
+* link:src/main/docs/project-requirements.adoc[Project requirements (summary view)]
+* link:src/main/docs/project-requirements.adoc[Project requirements (full specification)]
+* link:src/main/docs/functional-requirements.adoc[Functional requirements catalogue]
+* link:src/main/docs/architecture-overview.adoc[Architecture overview]
+* link:src/main/docs/operational-controls.adoc[Operational controls]
+* link:src/main/docs/thread-safety-guide.adoc[Thread-safety guide]
+* link:src/main/docs/thread-security-review.adoc[Security review]
+* link:src/main/docs/thread-performance-targets.adoc[Performance targets]
+* link:src/main/docs/decision-log.adoc[Decision log]
+* link:systemProperties.adoc[System properties reference]
+
 [source,java]
 ----
 el.addHandler(eh0);
@@ -155,6 +170,51 @@ determines which of its child event loops the `EventHandler` is installed on.
 The second use of `HandlerPriority` is to enable each (child) event loop to determine how often each
 `EventHandler` is called e.g. `HandlerPriority.HIGH` handlers are executed more than `HandlerPriority.MEDIUM` handlers.
 
+An `EventGroup` is configured with a set of supported handler priorities (by default all priorities).
+Loops are only created for enabled priorities and attempts to add a handler whose priority has no corresponding loop result in an `IllegalStateException`.
+If the configured priority set is empty, only the monitor loop is present and handlers with any other priority are rejected.
+
+== Requirements and Decisions
+
+The functional requirements for Chronicle Threads are captured in link:src/main/docs/project-requirements.adoc[project-requirements.adoc].
+Architectural and operational decisions, including event-loop threading and disk-space monitoring policies, are captured in link:src/main/docs/decision-log.adoc[decision-log.adoc].
+
+== Advanced Usage Example
+
+The following example shows how two `EventGroup` instances can be used to separate a latency-critical trading pipeline from slower operational tasks in the same JVM.
+
+[source,java,opts=novalidate]
+----
+// Latency-sensitive trading group on isolated cores
+EventGroup tradingGroup = EventGroup.builder()
+        .withName("trading-eg")
+        .withPauserMode(PauserMode.BUSY)
+        .withBinding("2-3") // bind to isolated cores for low jitter
+        .build();
+
+tradingGroup.addHandler(new OrderBookHandler());
+tradingGroup.addHandler(new RiskCheckHandler());
+
+// Operational / housekeeping group on shared cores
+EventGroup opsGroup = EventGroup.builder()
+        .withName("ops-eg")
+        .withPauserMode(PauserMode.BALANCED)
+        .withBinding("4-5") // less aggressive CPU usage
+        .build();
+
+opsGroup.addHandler(new MetricsExportHandler());
+opsGroup.addHandler(new DiskSpaceMonitorHandler());
+
+tradingGroup.start();
+opsGroup.start();
+
+// On shutdown
+opsGroup.close();
+tradingGroup.close();
+----
+
+The architecture overview (link:src/main/docs/architecture-overview.adoc[architecture-overview.adoc]) and operational controls (link:src/main/docs/operational-controls.adoc[operational-controls.adoc]) explain how to choose bindings, pausers and monitoring settings for such topologies.
+
 == Pausers
 
 Chronicle Threads provides a number of implementations of the

pom.xml

@@ -32,7 +32,7 @@
             <dependency>
                 <groupId>net.openhft</groupId>
                 <artifactId>third-party-bom</artifactId>
-                <version>3.27ea5</version>
+                <version>3.27ea7</version>
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>