Harden Chronicle Threads docs and runtime introspection; enable section numbering and add loop introspection tests

[peter-lawrey]

This change tightens our contributor guidance, introduces an opt-in code-review QA profile, relocates and expands project docs, and applies a set of safe, low-risk refinements across event-loop code and tests. No public API surface is intentionally changed; classes that previously implemented interfaces still do so via their superclass.

---

Why

• Make expectations explicit for agents/humans (British English, ISO-8859-1, Nine-Box tags).
• Give reviewers a one-command quality gate (-Pcode-review) that runs Checkstyle, PMD, SpotBugs(+FindSecBugs), and JaCoCo.
• Move requirements/decisions into src/main/docs/ and add missing operator/architecture content.
• Polish thread/monitor code for clarity, precision, and diagnosability, while keeping behaviour stable.
• Grow tests around disk monitoring, loop introspection, pauser timeouts, and thread monitors.

---

What changed

Contributor guidance & docs

• AGENTS.md

  • Reflowed tables for readability; kept British English rules.
  • Improved Javadoc Do/Don’t table.
  • “Project requirements” links now point to src/main/docs/….
  • Best-practices and AI-agent guidelines rewrapped for clarity.
  • Tag taxonomy (Nine-Box) laid out in a consistent table.

• Docs relocated/added

  • Moved: src/main/adoc/* → src/main/docs/*.

  • New docs:

    • project-requirements.adoc (sectnums, clearer scope/IDs).

    • decision-log.adoc (tidier structure; same decisions).

    • Architecture/operations/perf/security/thread-safety guides:

      • thread-architecture-overview.adoc
      • thread-operational-controls.adoc
      • thread-performance-targets.adoc
      • thread-security-review.adoc
      • thread-thread-safety-guide.adoc

• README.adoc / LICENSE.adoc

  • Reduced line-wrap noise; minor headings and wording tweaks.

• docs/images/source/image1.svg

  • XML tidy (attrs and whitespace); no visual change.

Build & quality

• pom.xml

  • Formatting clean-ups and self-closing tags.

  • Properties added/pinned:

    • Checkstyle, SpotBugs, FindSecBugs, PMD, JaCoCo versions.
    • JaCoCo thresholds (see profile below).
    • Binary compatibility threshold property.

  • New opt-in code-review profile:

    • Checkstyle (project config + suppressions).
    • SpotBugs + FindSecBugs (exclude list).
    • PMD (minimal ruleset + excludes).
    • JaCoCo prepare/report/check.
    • Note: thresholds set to 0.0 in this first cut to let teams introduce the profile without red builds; raise in follow-ups.

• New config files

  • src/main/config/checkstyle.xml
  • src/main/config/checkstyle-suppressions.xml
  • src/main/config/pmd-ruleset.xml
  • src/main/config/pmd-exclude.properties
  • src/main/config/spotbugs-exclude.xml

Thread/event-loop refinements (behaviour-preserving)

• Prefer ExecutorService#execute over submit where result futures are unused.

• Stricter visibility (private/final/volatile) on select fields and helpers.

• Safer calculations and logs:

  • Millisecond conversions use floating-point with rounding (clearer perf logs).
  • Disk-space % computed via precise fraction + rounding.

• Loop execution:

  • Simplified loops (replace switch/fall-through unrolls with clear for-loops) while retaining ordering/semantics.
  • isRunningOnThread and shutdown sequences made more robust.

• Builders:

  • Priority set defensive copy (EnumSet.copyOf).

• Minor Javadoc clean-ups, parameter alignment, and explicit suppressions where appropriate.

Tests (new/expanded)

• Loop introspection and pending-handler close paths.
• Thread monitors (log gating).
• DiskSpaceMonitor aggregator and threshold setter.
• Pauser timeout behaviour (deadline logic clarified).
• EventGroup and Medium/Vanilla loops: timing, ordering, and lifecycle assertions.
• JUnit imports tidied; added deterministic helpers.

Misc

• system.properties and systemProperties.adoc table formatting harmonised.

---

Compatibility

• API: No intentional breaking changes. Classes that once declared implements EventLoop or Closeable still inherit those via AbstractLifecycleEventLoop/AbstractCloseable. Method signatures remain stable.
• Runtime: Changes are conservative (logging precision, loop internals readability). Behaviour and performance characteristics are unchanged in normal operation.

---

How to use the QA profile

# Run the full quality gate locally (opt-in)
mvn -q -Pcode-review verify

• Expect Checkstyle/SpotBugs/PMD/JaCoCo to run.
• Current thresholds are permissive (0.0) to bootstrap adoption; we will ratchet these up once teams are green.

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud