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

[peter-lawrey]

Functional changes

1. SLF4J / Log4j / JUL integration and behaviour

• SLF4J 2.x as the default provider

  • logger-slf4j-2 is now the primary SLF4J binding (via SLF4JServiceProvider), with a new Slf4jProviderHealthCheckTest ensuring the Chronicle provider is discoverable on the classpath.
  • ChronicleLoggerFactory in both logger-slf4j (1.x) and logger-slf4j-2 now implement a shared ChronicleLoggerFactoryControl interface and expose a reload() hook so tests and tools can reset state consistently.

• Legacy SLF4J 1.x support and bridges

  • Re-enabled the logger-slf4j, logger-logback, logger-log4j-1 and logger-log4j-2 modules in the root pom.xml, so all bindings are built and tested again.

  • Reworked Log4j 1.x integration:

    • logger-log4j-1 now uses pure Log4j 1 APIs in production and slf4j-reload4j test-scope as the SLF4J bridge for legacy callers.
    • New Slf4jBridgeChronicleLogTest verifies that SLF4J log calls still reach the Chronicle Log4j 1 appender via the bridge.

  • Log4j 2 tests now use org.apache.logging.log4j.Logger directly instead of SLF4J, avoiding accidental provider confusion.

• JUL / JCL test logging

  • Switched logger-jcl and logger-jul test dependencies from slf4j-nop to slf4j-simple so tests emit visible console output when they fail.
  • AbstractChronicleHandler in logger-jul now exposes setPath/getPath so tests can assert handler wiring reliably, and ChronicleHandlerConfig’s level parsing is simplified to rely on Level.parse(..).

• SLF4J SimpleLogger wiring and error paths

  • SLF4J 1.x/2.x SimpleLoggerConfiguration now logs configuration failures to System.err and prints stack traces instead of using the deprecated Reporter/Util.report helpers.
  • SLF4J SimpleLogger has been cleaned up (javadoc, switch default, explicit IllegalStateException for unknown levels) but preserves upstream semantics; deprecation warnings are suppressed where we intentionally retain 1.x base classes for compatibility.

2. Chronicle logging configuration and lifecycle

• Configuration loading

  • ChronicleLogConfig.load(InputStream) now uses try-with-resources, logs a clear error to System.err on IOException, and returns null instead of silently swallowing failures.
  • ChronicleLogConfig.getBoolean(..) overloads now normalise values via "true".equalsIgnoreCase(..) and return a concrete Boolean instead of null where previously used in defaulted paths; call-sites using the defval overload retain their existing behaviour.

• Manager and appender resilience

  • ChronicleLogManager.clear() now logs failures to close individual ChronicleLogWriter instances to System.err and continues clearing, instead of silently dropping exceptions.
  • When append=false is configured, newChronicle(..) now logs that queue clearing is not yet supported instead of invoking a code path that throws UnsupportedOperationException.
  • LogAppenderConfig.setProperty(..) logs a concise error to System.err if reflective configuration fails, making mis-typed properties visible.

• Tools and interrupt handling

  • ChronicleLogReader.processLogs(..) now honours thread interruption when waitForIt=true: on InterruptedException it sets the interrupt flag and breaks out of the loop instead of sleeping indefinitely. This prevents tools from hanging when their thread is cancelled.

3. Module wiring and tests

• Root POM module set

  • logger-slf4j, logger-logback, logger-log4j-1 and logger-log4j-2 are now active modules again, restoring a full build and test matrix for all bindings.

• Test updates and refactors

  • SLF4J 1.x tests (Slf4jChronicleLoggerTest, Slf4jChronicleLoggerPerfTest, Slf4jTestBase) now discover the logger factory via either the SLF4J 2.x ChronicleServiceProvider or the classic StaticLoggerBinder, and call reload() through the new ChronicleLoggerFactoryControl interface.
  • Log4j 1.x tests now use org.apache.log4j.Logger and Level directly, with message formatting via simple string concatenation instead of SLF4J {} templates, aligning the tests with the actual appenders in use.
  • JUL tests close configuration streams via try-with-resources to avoid descriptor leaks.

---

Non-functional changes

1. Agent guidelines, encoding policy, and security checklist

• AGENTS.md refinement

  • Tightened the encoding policy from “ASCII-7 only” to ISO-8859-1 (still disallowing smart quotes, non-breaking spaces and arbitrary Unicode) and added practical checks (iconv, IDE settings) to enforce it.
  • Expanded build guidance to emphasise mvn -q clean verify from a clean checkout, plus a short section on when to open a PR and how to keep changes focused.
  • Added an explicit security checklist for reviewers (input validation, authentication/authorisation, resource exhaustion, secret handling) and guidance on documenting intentional safety trade-offs in Javadoc and .adoc files.
  • Clarified SLF4J policy: SLF4J 2.x via logger-slf4j-2 is the default; legacy SLF4J 1.7.x call-sites should use explicit bridges such as slf4j-reload4j.

2. Documentation and requirements catalogue

• New and updated docs

  • CLAUDE.md and GEMINI.md added as per-tool guides explaining:

    • Module layout, build/test commands and quality checks.
    • Chronicle Logger’s architecture, dependencies (chronicle-core, chronicle-bytes, chronicle-queue).
    • Requirements structure (Nine-Box CLG-* tags) and how agents should respect British English + ISO-8859-1.

  • README.adoc:

    • Normalised AsciiDoc header (:toc:, :lang: en-GB, :source-highlighter: rouge).
    • Clarified SLF4J compatibility matrix and recommended use of logger-slf4j-2 plus explicit bridges for older code.
    • Added a “Further reading” section linking to architecture, requirements and decision docs.

  • adoc/project-requirements.adoc, src/main/docs/project-requirements.adoc, functional-requirements.adoc, architecture-overview.adoc, code-review-playbook.adoc, testing-strategy.adoc and decision-log.adoc:

    • Aligned on Nine-Box tags (CLG-FN-*, CLG-NF-*, CLG-DOC-*, CLG-OPS-*).
    • Called out SLF4J 2.x as the default API with explicit bridging for SLF4J 1.x.
    • Documented testing strategy, including provider health checks and bridge coverage.
    • Added CLG-FN-006 to capture the decision to default to SLF4J 2.x while supporting legacy bridges.

3. Test logging and diagnostics

• Swapped silent test loggers (slf4j-nop) for console loggers (slf4j-simple or logger-logback test-scope) in several modules so that misconfigurations and failures produce visible output.
• Added targeted System.err messages in configuration and property-binding code paths to make failure modes explicit without changing successful behaviour.

Overall, this PR makes Chronicle Logger SLF4J-2-friendly by default, keeps SLF4J 1.x and Log4j 1/2 paths working via explicit bridges, and strengthens the documentation, agent guidance and testing around those contracts.