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

[peter-lawrey]

This PR strengthens the Chronicle Test Framework’s documentation for AI agents, introduces an explicit decision log, and aligns the module with the latest OpenHFT dependency BOM. It also includes several minor API/quality tweaks and test harness improvements.

Functional changes

• Dependency alignment:

  • Update to third-party-bom 3.27ea5 → 3.27ea7 in pom.xml, pulling in the latest curated dependency set from the OpenHFT stack (e.g. updated logging stack and related libraries via the BOM).
  • Runtime behaviour should remain compatible, but consumers inherit the newer transitive versions from the BOM.

• DtoTester builder API refinement:

  • DtoTester.Builder.addMutator(...) drops the unused type parameter <R> and now returns Builder<T> directly in both the interface and DtoTesterBuilder implementation.
  • This is source-breaking only for callers that explicitly used the generic (e.g. builder.<SomeType>addMutator(...)), but is otherwise behaviour-preserving and simplifies the public API.

• Process / I/O and charset correctness in tests:

  • InternalJavaProcessBuilder now uses File.pathSeparator instead of looking up the path.separator system property and uses SLF4J parameterised logging for process output formatting.

  • TcpProxyTest:

    • Uses ISO_8859_1 explicitly for encoding/decoding bytes in the proxy round-trip tests, aligning tests with our documented charset guidance.
    • Fixes logger initialisation to use TcpProxyTest.class and cleans up log message formatting.

  • MappedFileUtil now reads /proc/self/maps via an InputStreamReader that explicitly uses StandardCharsets.UTF_8, ensuring predictable decoding and safer error handling when enumerating mapped files on Linux.

Overall, the core library behaviour is unchanged; the main externally visible change is the cleaner DtoTester.Builder method signature and the dependency versions coming from the BOM.

Non-functional changes

AI agent and contributor guidance

• AGENTS.md

  • Relax language/encoding policy from ASCII-7 to ISO-8859-1 while still forbidding smart quotes, non-breaking spaces, and stray Unicode; document how to check for invalid characters (iconv, IDE inspections).

  • Add a link to the University of Oxford style guide for British English usage.

  • Clarify Javadoc expectations and add an inline “good vs bad” comment example to discourage noisy comments.

  • Recommend mvn -q clean verify from a clean checkout and note that exit code 0 is required before opening a PR.

  • Add guidance on when to open PRs (build green, focused scope, linked issues/decisions).

  • Expand reviewer checklist:

    • Traceability to requirements/decision tags.
    • Keeping documentation, tests, and code updated together.
    • Considering diagrams/examples for future maintainers.

  • Introduce a security checklist for every PR (validation, authn/authz, encoding, resource exhaustion, timing attacks; no secrets in VCS; call out deliberate security trade-offs in docs).

  • Refine AsciiDoc guidance:

    • Explain list nesting and description list patterns.
    • Specify use of :sectnums: and consistent document headers for numbered sections.

  • Update references to the Decision Log and Project Requirements to point to src/main/docs/decision-log.adoc and src/main/docs/project-requirements.adoc.

• CLAUDE.md (new)

  • Add a dedicated guide for Claude Code when working in this repository:

    • Overview of CTF’s purpose, package structure, and core capabilities (combinatorial generators, API metrics, DTO testing, process/mapped file utilities).
    • Explicit language/character-set rules (mirroring AGENTS), Javadoc practices, and test patterns (dynamic tests, DTO testing, Bootstrapping requirements).
    • Build commands and notes on Surefire forking behaviour.
    • Summary of code-structure rules enforced by CodeStructureVerifier (no external inheritance from .internal packages, Bootstrap.bootstrap() in main methods, etc.).

  • This gives AI agents a project-specific handbook, improving AI-assisted contributions while keeping them aligned with our existing conventions.

Requirements and decision documentation

• Decision log (new): src/main/docs/decision-log.adoc

  • Introduces a central Decision Log for CTF using the Nine-Box taxonomy and the AGENTS.md template.

  • Records three initial decisions:

    • [CTF-DOC-001] Adoption of ADRs and a repo-local decision log (docs-as-code).
    • [CTF-FN-002] Strategy for AI-driven enhancement of CTF (AI-consumable APIs, AI-identifiable refactorings).
    • [CTF-NF-P-003] Performance-first design for data generators (ensuring permutations/combinations remain efficient and controlled).

  • Establishes a clear place for future architectural and requirement decisions, improving traceability for both humans and AI tools.

• Project requirements refactor:
  src/main/adoc/project-requirements.adoc → src/main/docs/project-requirements.adoc

  • Moves the requirements into the new src/main/docs tree and aligns the header with AGENTS guidance (:toc:, :sectnums:, :lang: en-GB, :source-highlighter: rouge).

  • Normalises section headings, breaks long paragraphs, and adds explicit anchors (e.g. [[REQ-FR-CORE-001]]) for individual requirements (FR and NFR).

  • Clarifies and re-flows text for:

    • Current state of CTF.
    • Functional requirements (core, UX, OpenHFT integration, AI-specific).
    • Non-functional requirements (performance, usability, maintainability, compatibility, documentation, stability).
    • AI-driven development strategy (AI for CTF and AI with CTF).

  • The document is now easier to cross-reference from code, ADRs, and PRs.

• README.adoc

  • Adds :lang: en-GB and :source-highlighter: rouge to the header to match our AsciiDoc conventions.

  • Adds a new “Quality and static analysis” section describing how to run the shared Chronicle quality stack:

    • mvn -P quality clean verify from an aggregator to run Checkstyle, SpotBugs and coverage checks.
    • mvn -P module-quality clean verify from the Chronicle-Test-Framework module (Java 11+) for module-focused SpotBugs runs.

Code quality and style improvements

• Javadoc and package-info clean-ups

  • Replace simple {@link Metric} / {@link Accumulator} in apimetrics/package-info.java with fully qualified references to avoid ambiguity.
  • Convert plain blank Javadoc lines into <p> where appropriate (PermutationUtil, internal.process package), making the documentation render cleanly.

• API and implementation tidy-ups

  • ThrowingConsumerException:

    • Makes serialVersionUID private static final, matching standard Serializable best practice and avoiding accidental external access.

  • VanillaNamedConsumer:

    • Annotates name() as returning @NotNull String for better null-safety signalling.

  • DtoTesterBuilder:

    • Aligns with the simplified DtoTester.Builder interface signature.
    • Removes obsolete commented-out legacy validation method.

• Tests and diagnostics

  • StandardDtoTester:

    • Removes unused helper method check(...), reducing dead code in the test harness.

  • DelegatesToInternal, DtoAlias, ExampleInternal:

    • Add targeted @SuppressWarnings and explicit “Intentional no-op” comments to clarify purpose in structure tests.

  • *DemoTest classes for combinations, permutations, lists, and products:

    • Add @SuppressWarnings("MappingBeforeCount") where the stream shape is intentional.

  • PermutationTest:

    • Simplifies lambda expressions in assertions for factorial boundary conditions, making tests more concise without changing coverage.

  • DtoTesterDemoTest:

    • Uses Objects.equals in MyDtoImpl.equals to clarify null-safe comparison.

Testing

• mvn -q clean verify (as per the updated AGENTS.md guidance).
• For full quality checks (recommended from an aggregator):

No behavioural regressions are expected in the core CTF runtime beyond the minor DtoTester.Builder signature change; most changes improve documentation, diagnostics, and test harness robustness.

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

Measures
0 Security Hotspots
70.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud