Align Chronicle Logger with SLF4J 2.x, re-enable legacy bindings, and tighten agent/requirements docs

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. | Non-ISO-8859-1 encodings (including other '8-bit ASCII' variants) are *not* portable and are therefore disallowed. |
+| Tools to check ISO-8859-1 compliance include `iconv -f ISO-8859-1 -t ISO-8859-1` and IDE settings that flag non-ISO-8859-1 characters. | These help catch stray Unicode or mis-encoded characters before code review. |
 
 ## Javadoc guidelines
 
@@ -26,25 +27,44 @@ 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.
 
-## Build & test commands
+Inline comments should also avoid noise. The following example shows the
+difference:
 
-Agents must verify that the project still compiles and all unit tests pass before opening a PR:
+```java
+// BAD: adds no value
+int count; // the count
+
+// GOOD: explains a subtlety
+// count of messages pending flush
+int count;
+```
+
+## Build, test, and quality commands
+
+Agents must verify that the project still compiles and all unit tests pass before opening a PR. Running from a clean checkout avoids stale artefacts:
 
 ```bash
 # From repo root
-mvn -q verify
+mvn -q clean 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,6 +73,14 @@ 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](adoc/decision-log.adoc) for the latest project decisions.
@@ -79,12 +107,13 @@ This tight loop informs the AI accurately and creates immediate clarity for all
 * **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.
+* SLF4J 2.x is the default API and provider via `logger-slf4j-2`; keep `logger-slf4j` for SLF4J 1.7.x only and use explicit bridges (for example `slf4j-reload4j`) when preserving old call sites.
 
 ## 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.
+* **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 +151,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.
@@ -159,3 +187,23 @@ section:: Top Level Section
 ### 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
+```

CLAUDE.md

@@ -0,0 +1,208 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+Chronicle Logger is a high-performance logging library built on Chronicle Queue. It provides adapters for major Java logging frameworks (SLF4J, Logback, Log4J 1/2, JUL, JCL) that write to binary Chronicle Queues rather than text files. This approach minimises logging overhead and enables sub-microsecond logging latency.
+
+**Key architectural principle:** Chronicle Logger writes synchronously to off-heap queues, ensuring the last log message is always visible before application termination whilst maintaining low latency through zero-allocation design.
+
+## Module Structure
+
+This is a multi-module Maven project with the following modules:
+
+* `logger-core` - Core API (`ChronicleLogWriter`, `ChronicleLogManager`) and configuration
+* `logger-slf4j` - SLF4J 1.x binding
+* `logger-slf4j-2` - SLF4J 2.x binding
+* `logger-logback` - Logback appender
+* `logger-log4j-1` - Log4J 1.2 appender
+* `logger-log4j-2` - Log4J 2.x appender
+* `logger-jul` - Java Util Logging handler
+* `logger-jcl` - Apache Commons Logging binding
+* `logger-tools` - CLI tools (`ChroniCat`, `ChroniTail`) and `ChronicleLogReader` API
+* `benchmark` - JMH performance benchmarks
+
+All binding modules depend on `logger-core` and translate framework-specific APIs into Chronicle Queue writes.
+
+## Build Commands
+
+### Full Build
+
+```bash
+# Clean build with tests
+mvn clean verify
+
+# Build without tests (faster)
+mvn clean install -DskipTests
+
+# Quiet build with tests
+mvn -q clean verify
+```
+
+### Module-Specific Builds
+
+```bash
+# Build single module with dependencies
+mvn -pl logger-slf4j -am clean install
+
+# Build single module without tests
+mvn -pl logger-core -am -DskipTests install
+```
+
+### Running Tests
+
+```bash
+# Run all tests in a module
+mvn -pl logger-slf4j test
+
+# Run single test class
+mvn -pl logger-core -Dtest=DefaultChronicleLogWriterTest test
+
+# Run specific test method
+mvn -pl logger-core -Dtest=DefaultChronicleLogWriterTest#testWrite test
+```
+
+### Running Benchmarks
+
+```bash
+cd benchmark
+mvn clean install
+# Run JMH benchmarks
+java -jar target/benchmarks.jar
+
+# Run specific benchmark
+java -jar target/benchmarks.jar <BenchmarkClassName>
+
+# Run with custom parameters
+java -jar target/benchmarks.jar -f 1 -wi 3 -i 5
+```
+
+### Code Quality
+
+```bash
+# Run Checkstyle (inherited from java-parent-pom)
+mvn checkstyle:check
+
+# Run SpotBugs
+mvn spotbugs:check
+
+# Run all quality checks with tests
+mvn clean verify
+```
+
+## Architecture Overview
+
+### Write Path
+
+1. Logging framework (e.g., SLF4J) receives a log call
+2. Binding checks log level against configured minimum
+3. If enabled, binding forwards event to `ChronicleLogWriter`
+4. `ChronicleLogWriter` serialises data into Chronicle Queue using configured wire type
+5. Write is synchronous but zero-allocation on hot path for minimal overhead
+
+### Configuration
+
+* Properties-based bindings (SLF4J, JCL): Use `chronicle.logger.properties` (classpath or path specified via `-Dchronicle.logger.properties`)
+* Native framework bindings (Logback, Log4J): Use XML configuration with `ChronicleAppender`/`ChronicleHandler`
+* `ChronicleLogManager` caches writers per queue path
+* Each logger requires distinct queue path; sharing paths between loggers is unsupported
+
+### Reading Logs
+
+Binary logs require tools to read:
+
+* `ChroniCat` - Dump log contents to STDOUT
+* `ChroniTail` - Stream log contents like Unix `tail -f`
+* `ChronicleLogReader` - Programmatic API for custom log processing
+
+Example:
+```bash
+mvn exec:java -Dexec.mainClass="net.openhft.chronicle.logger.tools.ChroniCat" \
+  -Dexec.args="/tmp/chronicle-logs/my-logger"
+```
+
+## Dependencies
+
+Chronicle Logger depends on:
+
+* `chronicle-core` - Low-level utilities
+* `chronicle-bytes` - Off-heap memory access
+* `chronicle-queue` - Persisted message queue
+
+Versions are managed through `chronicle-bom` imported in the parent POM.
+
+## Documentation Structure
+
+Documentation follows Chronicle standards:
+
+* Location: `src/main/docs/` (AsciiDoc format)
+* Key files:
+  - `architecture-overview.adoc` - High-level architecture
+  - `project-requirements.adoc` - Requirements catalogue with Nine-Box tags (e.g., `CLG-FN-001`)
+  - `functional-requirements.adoc` - Functional requirements summary
+  - `decision-log.adoc` - Architecture Decision Records
+  - `testing-strategy.adoc` - Testing approach and traceability
+  - `code-review-playbook.adoc` - Code review guidelines
+* Format: British English, ISO-8859-1 character set
+* Requirements use Nine-Box taxonomy: `FN` (Functional), `NF-P` (Performance), `NF-S` (Security), `NF-O` (Operability), etc.
+
+See `AGENTS.md` for detailed documentation standards and contribution guidelines.
+
+## Code Conventions
+
+* Follow Chronicle coding standards in `AGENTS.md`
+* British English spelling (except technical US terms like `synchronized`)
+* ISO-8859-1 character set only
+* Javadoc should explain _why_ and _how_, not restate obvious signatures
+* Preserve Nine-Box requirement tags in comments (e.g., `// CLG-NF-P-001: Zero-allocation write path`)
+
+## Common Development Tasks
+
+### Adding Support for New Logging Framework
+
+1. Create new module `logger-<framework>` following existing patterns
+2. Implement framework-specific adapter/appender/handler
+3. Delegate to `ChronicleLogWriter` from `logger-core`
+4. Add configuration support (properties or framework-native)
+5. Write tests extending appropriate base test class
+6. Add module to parent `pom.xml` `<modules>` section
+
+### Modifying Log Format
+
+1. Changes to `ChronicleLogWriter` interface affect all bindings
+2. Update serialisation in `DefaultChronicleLogWriter`
+3. Update deserialisation in `ChronicleLogReader` (logger-tools)
+4. Update CLI tools if record schema changes
+5. Update relevant tests across modules
+
+### Performance Testing
+
+Benchmark changes that affect write path:
+
+```bash
+cd benchmark
+mvn clean install
+java -jar target/benchmarks.jar -f 1
+```
+
+Compare results with baseline in README.adoc.
+
+## Important Notes
+
+1. **Log4Shell Immunity**: `logger-log4j-2` does not suffer from log4shell vulnerability as it does not reuse Log4J2 message formatting machinery
+
+2. **Queue Path Uniqueness**: Each logger must have a distinct Chronicle Queue path. Two loggers sharing the same path is unsupported and will cause errors
+
+3. **Non-Hierarchical Loggers**: Logger names like `my.domain.package` and `my.domain` are distinct; no hierarchical grouping is applied
+
+4. **Synchronous Writes**: All writes are synchronous to ensure last messages are visible before application termination. This differs from async appenders but maintains sub-microsecond latency through zero-allocation design
+
+5. **Binary Format**: Logs are binary (not text). Use provided tools (`ChroniCat`, `ChroniTail`) or `ChronicleLogReader` API to read them
+
+## Related Documentation
+
+* `AGENTS.md` - Detailed contribution guidelines, build commands, documentation standards
+* `README.adoc` - Project overview, configuration examples, performance metrics
+* `src/main/docs/architecture-overview.adoc` - Detailed architecture documentation
+* `src/main/docs/project-requirements.adoc` - Complete requirements catalogue