Clarify AI agent workflow, add decision log, and align CTF with latest BOM

AGENTS.md

@@ -10,33 +10,47 @@ 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 you must show a symbol that does not exist in ASCII-7, spell it out (`micro-second`, `>=`, `:alpha:`, `:yes:`) rather than inserting Unicode. | 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.
 
 ## Commit-message & PR etiquette
 
@@ -45,34 +59,48 @@ mvn -q verify
 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?*
 * Does the Javadoc explain the code's *why* and *how* that a junior developer would not be expected to work out?
+* Are the documentation, tests and code updated together so the change is clear?
+* 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
 
 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.
 
-### Benefits
+### Benefits of Real-Time Documentation
 
-* **Confidence in Documentation**: Accurate docs prevent "miscommunications" that derail real-world outcomes.
-* **Better Onboarding**: An up-to-date AsciiDoc set means new developers grasp the system's design and requirements more quickly.
-* **Incremental Changes**: Thanks to the incremental mode, AIDE flags any newly updated files so you can keep the documentation synchronised.
-
-### Benefits of Keeping Requirements, Tests, and Code In Sync
-
-* **Reduced Drift**: Minimises gaps between documentation, tested behaviour, and implementation.
-* **Faster Feedback**: AI can quickly generate stubs based on docs/tests and highlight inconsistencies discovered during analysis.
-* **Better Quality**: Frequent checks align the code with specified requirements and verifiable tests.
-* **Smoother Onboarding**: Up-to-date AsciiDoc clarifies the system for new developers or team members switching contexts.
+* **Confidence in documentation**: Accurate docs prevent miscommunications that derail real-world outcomes.
+* **Reduced drift**: Real-time updates keep requirements, tests and code aligned.
+* **Faster feedback**: AI can quickly highlight inconsistencies when everything is in sync.
+* **Better quality**: Frequent checks align the implementation with the specified behaviour.
+* **Smoother onboarding**: Up-to-date AsciiDoc clarifies the system for new developers.
+* **Incremental changes**: AIDE flags newly updated files so you can keep the documentation synchronised.
 
 ### Best Practices
 
@@ -85,8 +113,8 @@ 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.
-  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.
+* **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.
 
@@ -119,13 +147,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:* ...
@@ -134,14 +161,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)
 ```
 
@@ -152,11 +179,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
+```

CLAUDE.md

@@ -0,0 +1,173 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Chronicle Test Framework (CTF) is a Java library providing test-data generators and API metrics tools for JUnit 4 and JUnit 5. It specialises in exhaustive test case generation through combinatorial utilities and provides OpenHFT-specific testing support.
+
+**Key capabilities:**
+- Combinatorial test data generation: `Permutation.of()`, `Combination.of()`, `Product.of()`, `Series.of()`
+- API metrics analysis for measuring public/internal API surface
+- Testing utilities for concurrency, resources, network, and processes
+- DTO testing utilities
+- Flaky test handling and exception tracking
+
+## Build Commands
+
+```bash
+# Full build and test (REQUIRED before opening PRs)
+mvn -q verify
+
+# Run tests only
+mvn -q test
+
+# Run a single test class
+mvn -q test -Dtest=ClassName
+
+# Run a single test method
+mvn -q test -Dtest=ClassName#methodName
+
+# Clean build
+mvn clean install
+
+# Skip tests (use sparingly)
+mvn -q install -DskipTests
+```
+
+**Important:** The surefire plugin uses `forkCount=4` and `reuseForks=true`, giving each test class its own JVM. System properties can be safely set per test class but not per method.
+
+## Code Architecture
+
+### Package Structure
+
+**Main packages:**
+- `net.openhft.chronicle.testframework` - Core utilities and combinatorial generators
+- `net.openhft.chronicle.testframework.apimetrics` - API metrics analysis (Metric, Accumulator, ApiMetrics)
+- `net.openhft.chronicle.testframework.dto` - DTO testing utilities
+- `net.openhft.chronicle.testframework.exception` - Exception tracking utilities
+- `net.openhft.chronicle.testframework.function` - Functional interfaces (NamedConsumer, ThrowingConsumer, TriConsumer)
+- `net.openhft.chronicle.testframework.process` - Java process management for multi-process tests
+- `net.openhft.chronicle.testframework.mappedfiles` - Memory-mapped file utilities
+- `net.openhft.chronicle.testframework.internal.*` - Implementation classes (not for external use)
+
+**Internal convention:** Packages with `.internal.` in the name or ending in `.internal` contain implementation classes. Non-internal classes must not extend internal classes (enforced by CodeStructureVerifier).
+
+### Combinatorial Test Generation
+
+The framework's core strength is exhaustive test data generation using:
+
+1. **Permutation** - All orderings of elements (factorial growth)
+2. **Combination** - All subsets of elements (power set)
+3. **Product** - Cartesian product (nested loop equivalent)
+4. **Series** - Numeric sequences for parameterised tests
+
+These integrate with JUnit 5's `@TestFactory` and `DynamicTest.stream()` for declarative exhaustive testing.
+
+### API Metrics Architecture
+
+The API metrics system uses a builder pattern:
+1. **Metric** - Defines what to measure (e.g., public methods, deprecated APIs)
+2. **Accumulator** - Defines how to group results (e.g., per class, per package)
+3. **ApiMetrics** - Container for aggregated results, separates public/internal packages
+
+Builder workflow: `ApiMetrics.builder()` → add packages → add metrics → add accumulators → `build()`
+
+Packages are classified as internal if they contain `.internal.` or end with `.internal`.
+
+### Delegation Pattern
+
+The framework uses a delegation builder (`Delegation.builder()`) to create delegator instances that forward method calls to delegate objects. This is used internally for creating proxy implementations.
+
+## Language and Character Set
+
+**CRITICAL:** Follow Chronicle Software's house rules from AGENTS.md:
+
+- Use **British English** spelling (`organisation`, `licence`) except technical US terms (`synchronized`)
+- **ASCII-7 only** (code-points 0-127) - no Unicode, smart quotes, or accented characters
+- Spell out symbols: `micro-second`, `>=`, not Unicode equivalents
+
+## Javadoc Guidelines
+
+**Write Javadoc that adds information beyond the method signature:**
+
+**Do:**
+- State behavioural contracts, edge cases, thread-safety guarantees, units, performance characteristics
+- Keep first sentence short (becomes summary line)
+- Use `@param` for constraints, `@throws` for conditions
+- Remove/rewrite autogenerated Javadoc for trivial getters/setters
+
+**Don't:**
+- Restate the obvious ("Gets the value", "Sets the name")
+- Duplicate parameter names/types unless adding explanation
+- Leave stale comments that contradict code
+- Pad comments to reach line-length targets
+
+## Testing Patterns
+
+### Dynamic Test Generation
+
+Prefer this pattern for exhaustive testing:
+
+```java
+@TestFactory
+Stream<DynamicTest> exhaustiveTest() {
+    return DynamicTest.stream(
+        Permutation.of(operation1, operation2, operation3),
+        Objects::toString,
+        operations -> {
+            // Test logic using operations
+        }
+    );
+}
+```
+
+### Main Method Requirements
+
+Any class with a `main` method must include a static initializer calling `net.openhft.chronicle.core.Bootstrap.bootstrap()` (enforced by CodeStructureVerifier).
+
+### DTO Testing
+
+Use `DtoTester.builder()` to test data transfer objects for proper equals/hashCode/toString implementation.
+
+## Project Requirements
+
+**Reference documents:**
+- `src/main/adoc/project-requirements.adoc` - Comprehensive requirements for AI-driven enhancements
+- Decision log referenced in requirements document
+
+**Key principles:**
+- Complement existing frameworks (JUnit/TestNG), don't replace them
+- Focus on exhaustive test data generation and OpenHFT-specific utilities
+- Design for AI-assisted test generation and refactoring
+- Maintain compatibility with JUnit 4, JUnit 5, and TestNG
+
+## Commit and PR Guidelines
+
+1. Subject line <= 72 chars, imperative mood: "Fix roll-cycle offset in ExcerptAppender"
+2. Reference JIRA/GitHub issue if exists
+3. Body: root cause → fix → measurable impact (use ASCII bullet points)
+4. **Run `mvn verify` before opening PR**
+5. Target branch for PRs: `ea` (not main)
+
+## AsciiDoc Formatting
+
+When editing `.adoc` files:
+
+**List indentation:**
+```asciidoc
+- top level
+* second level
+  ** third level
+```
+
+**Emphasis:** Use `_emphasis_` for italics, `*bold*` for bold
+
+## Code Structure Enforcement
+
+The framework includes ArchUnit-based structure verification in `CodeStructureVerifier`:
+- Non-internal classes must not extend internal classes
+- Main methods must invoke Bootstrap
+- DTO aliases must invoke Bootstrap.bootstrap()
+
+These rules are tested and enforced at build time.

README.adoc

@@ -4,6 +4,8 @@
 :toc: macro
 :toclevels: 2
 :icons: font
+:lang: en-GB
+:source-highlighter: rouge
 
 image:https://maven-badges.herokuapp.com/maven-central/net.openhft/chronicle-test-framework/badge.svg[Maven Central,link=https://maven-badges.herokuapp.com/maven-central/net.openhft/chronicle-test-framework]
 image:https://javadoc.io/badge2/net.openhft/chronicle-test-framework/javadoc.svg[Javadoc,link="https://www.javadoc.io/doc/net.openhft/chronicle-test-framework/latest/index.html"]
@@ -237,3 +239,10 @@ They help to group metric counts in common ways.
 
 The convenience factories in `Accumulator` expose the first two suppliers for general use.
 The others are mainly for internal analyses but may be reused when custom behaviour is needed.
+
+== Quality and static analysis
+
+Chronicle Test Framework uses the shared Chronicle quality configuration provided by the parent POMs.
+
+* From an aggregator that includes this module, run `mvn -P quality clean verify` to execute Checkstyle and SpotBugs with coverage checks.
+* For a module-focused SpotBugs run on Java 11 or newer, run `mvn -P module-quality clean verify` in the `Chronicle-Test-Framework` project.