Add AI agent guidance and restructure Zero-Allocation Hashing docs

[peter-lawrey]

Introduce shared AI/agent guidelines for Chronicle projects, add a Claude-specific contributor guide for this repository, and bring the Zero-Allocation Hashing documentation into line with the new en-GB / AsciiDoc house style and Nine-Box requirements taxonomy. Code changes are limited to documentation comments and very minor internal refactors; no runtime behaviour is intended to change.

---

Functional changes

No user-visible or API changes are intended.

• Hashing algorithms

  • CityAndFarmHash_1_1 and MurmurHash_3 have small internal refactors (final locals, comment clarification, reordered local variable usage) that preserve the original logic and data flow.
  • XxHash.hashLong(long) is slightly rearranged for clarity (input normalisation happens before hash initialisation), but the resulting hash value is unchanged.

• Access API Javadoc

  • Access.toCharSequence(java.nio.ByteOrder) has its @param documentation reordered and clarified; method signature and behaviour are unchanged.

Overall, no changes are expected to the hash outputs, performance characteristics, or public APIs. This PR should be behaviour-neutral.

---

Non-functional / documentation changes

• New AI/agent house rules (AGENTS.md)

  • Add a repository-agnostic guide for AI agents, bots, and humans that covers:

    • Language & character-set policy: British English, ISO-8859-1 (except in string literals), no smart quotes or stray Unicode; use textual forms such as micro-second, >=, :alpha:, :yes:.
    • Javadoc guidelines: focus on behavioural contracts, edge cases, thread-safety, units, performance characteristics; avoid noise like “Gets the value”.
    • Build & test expectations: run mvn -q verify from repo root before opening PRs.
    • Commit / PR etiquette: <= 72 char imperative subject lines, root-cause → fix → measurable impact in the body.
    • Real-time documentation: keep .adoc, tests, and code in sync; encourage doc-first for new work.
    • Company-wide tagging: introduce the Nine-Box taxonomy (FN, NF-P, NF-S, NF-O, TEST, DOC, OPS, UX, RISK) plus ALL-* for global decisions.
    • ADR template and basic AsciiDoc formatting guidelines (lists, emphasis, headings).

• Claude-specific contributor guide (CLAUDE.md)

  • Add a detailed guide tailored to Claude Code for this repository:

    • Project overview for Zero-Allocation Hashing and its zero-allocation goals.
    • Canonical Maven build and test commands (including targeted test runs).
    • Architecture and key abstractions: LongHashFunction, LongTupleHashFunction, Access<T>, UnsafeAccess, string hashing strategies, and the supported algorithms (CityHash, FarmHash, MurmurHash3, xxHash, XXH3, wyHash, MetroHash).
    • Project conventions: British English, ISO-8859-1, zero-allocation constraints, immutable/stateless hash functions, runtime string layout detection.
    • Documentation workflow: keep src/main/docs/*.adoc aligned with code and tests, and reference ADRs in changes.

• Documentation structure & AsciiDoc header clean-up

  • README.adoc

    • Move project attributes into the header line and add:

      • :lang: en-GB
      • :source-highlighter: rouge
      • :pp: ++

    • Keeps Chronicle branding and AsciiDoc attributes together in a consistent style.

  • Docs converted to proper document headers with attributes

    • Promote several == section headings to top-level document titles (=) and add shared attributes:

      • :toc:
      • :lang: en-GB
      • :source-highlighter: rouge

    • Applies to:

      • algorithm-profiles.adoc
      • architecture-overview.adoc
      • change-log-template.adoc
      • invariants-and-contracts.adoc
      • performance-benchmarks.adoc
      • specifications.adoc
      • testing-strategy.adoc
      • unsafe-and-platform-notes.adoc

    • Replaces the manual toc::[] blocks with automatic table-of-contents via :toc:.

  • Minor editorial fixes

    • Normalise punctuation and wording (e.g. Google's, Appleby's, >= 32 byte etc.).
    • Keep ranges and comparisons consistent (e.g. 1-3, 4-7, >=32).

• New decision log (src/main/docs/decision-log.adoc)

  • Introduce ADRs documenting key architectural choices, including:

    • ADR-001: use of sun.misc.Unsafe for memory access.
    • ADR-002: little-endian canonicalisation for deterministic hashes across architectures.
    • ADR-003: Access<T> strategy pattern for input abstraction.
    • ADR-004: reflective String value access (compact strings).
    • ADR-005: stateless, immutable hash functions.
    • ADR-006: handling 128-bit hashes via LongTupleHashFunction and caller-managed long[] buffers.

• New requirements document (src/main/docs/project-requirements.adoc)

  • Capture functional and non-functional requirements for Zero-Allocation Hashing:

    • Functional: required algorithms, supported input types, seeding, determinism, cross-platform behaviour.
    • Non-functional: zero-allocation guarantees, performance baselines, thread-safety, JDK/JVM compatibility, and constraints on API design (no ThreadLocal, extensible Access pattern).

• Specification & strategy docs aligned with house style

  • specifications.adoc, testing-strategy.adoc, invariants-and-contracts.adoc, performance-benchmarks.adoc, and unsafe-and-platform-notes.adoc now:

    • Use = Title heading style.
    • Declare :lang: en-GB and :source-highlighter: rouge.
    • Rely on :toc: instead of toc::[].

---

Notes

• This PR is primarily about developer experience and documentation: it makes Zero-Allocation Hashing friendlier to AI tools and humans, and aligns the repo with Chronicle’s emerging AGENTS/ADR/Nine-Box conventions.
• No changes are expected in hash outputs, API signatures, or runtime performance; any behavioural regression would be unintended.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud