Merge houliston/scheduler and integrate typed priorities with lock-free scheduler.

Rebase was abandoned after conflicts across 73 commits; merge scheduler into
priority-changes instead. Maps the seven-level PriorityLevel DSL enum onto five
scheduler buckets, keeps ThreadPriority RAII, and updates scheduler/Group/Pool
code paths and docs for the typed priority model.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: TrentHouliston

.github/copilot-instructions.md

@@ -0,0 +1,131 @@
+# GitHub Copilot Instructions
+
+This repository contains NUClear — a C++ reactive framework for robot software.
+
+## Project Overview
+
+NUClear is a C++14 message-passing framework built around reactive programming.
+Reactors define event-driven callbacks using a domain-specific language (DSL) of template words.
+The framework handles threading, scheduling, and data routing automatically.
+
+### Core Components
+
+- **PowerPlant**: Top-level container that manages the system lifecycle
+- **Reactor**: Base class for user modules that define reactions
+- **DSL Words**: Template parameters that define triggering and data access (`Trigger`, `With`, `Every`, etc.)
+- **Threading**: Pool-based scheduler with priority queuing and group synchronisation
+- **Extensions**: Plugin system for IO, networking, timers, and tracing
+
+### Build System
+
+- CMake with C++14 target (`cxx_std_14`)
+- Catch2 for unit testing (fetched via CMake)
+- Platform support: Linux, macOS, Windows
+
+## Code Quality Standards
+
+- **Language Standard**: C++14 (do not use C++17 or later features)
+- **Formatting**: clang-format
+- **Linting**: clang-tidy (config in `cmake/ClangTidy.cmake`)
+- **Testing**: Catch2, run via CTest
+- **Language**: American English for all code, comments, and documentation
+
+### Code Style
+
+- **Clean Changes**: When making changes don't leave behind comments describing what was once there; comments should always describe code as it exists
+- **API Evolution**: When making changes don't leave behind backwards-compatible interfaces for internal APIs; there should always be a complete clean changeover
+- **Property Access**: Assume fields that should exist do exist directly; rely on errors if they don't rather than adding unnecessary null checks
+
+## Documentation Standards
+
+Documentation lives in `docs/` and is built with MkDocs Material.
+All documentation files are Markdown.
+
+### Markdown Formatting
+
+- **Formatter**: mdformat (config in `pyproject.toml`)
+- **Semantic Line Breaks**: Follow the [Semantic Line Breaks specification (SemBr)](https://sembr.org/)
+  - One sentence per line
+  - Break after sentences (`.`, `!`, `?`)
+  - Break after independent clauses (`,`, `;`, `:`, `—`) when it improves readability
+  - Break after dependent clauses for clarity when lines are long
+  - **Never break lines based on column count**
+  - If a line exceeds ~120 characters, consider simplifying the prose rather than wrapping mid-sentence
+  - Example:
+    ```markdown
+    NUClear is a reactive framework for building modular robot software.
+    It uses a domain-specific language embedded in C++ templates to define event-driven callbacks.
+
+    Each module is a Reactor that declares what data it needs,
+    and the framework handles threading and scheduling automatically.
+    ```
+
+### Writing Style
+
+- **Tone**: Friendly and informative
+- **Perspective**: Use second-person ("you" and "your") for user-facing documentation
+- **Language**: American English with sentence case for titles
+- **Clarity**: Write for non-native English speakers; avoid jargon without explanation
+- **Formatting in prose**:
+  - Use backticks for: type names, function names, file paths, DSL words, template parameters
+  - Use sentence case for headings (capitalize only the first word and proper nouns)
+  - Avoid abbreviations when possible
+
+### Documentation Structure (Diátaxis)
+
+The docs follow the [Diátaxis framework](https://diataxis.fr/):
+
+| Section        | Purpose                              | Path               |
+| -------------- | ------------------------------------ | ------------------ |
+| Getting started | Tutorials for new users             | `getting-started/` |
+| Concepts       | Explanation of architecture          | `concepts/`        |
+| How-to guides  | Task-oriented recipes                | `how-to/`          |
+| Reference      | Complete DSL/API reference           | `reference/`       |
+| Explanation    | Deep-dive background material        | `explanation/`     |
+| Contributing   | Developer setup and style guide      | `contributing/`    |
+
+### Code Examples in Documentation
+
+- All C++ examples should compile conceptually (correct syntax, proper includes)
+- Use `#include "nuclear"` as the canonical include
+- Examples should be self-contained where possible
+- Verify API usage against source code — do not guess signatures or return types
+
+### Documentation Tooling
+
+```bash
+# Install docs dependencies
+uv sync --group docs
+
+# Preview documentation
+uv run mkdocs serve
+
+# Format all markdown files
+uv sync --group dev
+uv run mdformat docs/
+```
+
+## Development Workflow
+
+### Building
+
+```bash
+mkdir build && cd build
+cmake .. -GNinja
+ninja
+```
+
+### Testing
+
+```bash
+cd build
+ctest
+```
+
+### Documentation Development
+
+```bash
+uv sync --group docs --group dev
+uv run mkdocs serve        # Live preview at http://127.0.0.1:8000
+uv run mdformat docs/      # Format markdown
+```

.github/workflows/linting.yaml

@@ -97,3 +97,20 @@ jobs:
 
       - name: CTCache Stats
         run: clang-tidy-cache --show-stats
+
+  markdown-format:
+    name: Markdown Formatting
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Check markdown formatting
+        run: uv run mdformat --check docs/

.gitignore

@@ -14,6 +14,7 @@
 
 # Build & CMake files
 build/
+build-*/
 CMakeCache.txt
 CMakeFiles
 Makefile
@@ -28,3 +29,7 @@ docs/doxygen
 docs/doxygen_sqlite3.db
 *.sublime-workspace
 .DS_Store
+site/
+.venv/
+
+site/

.readthedocs.yaml

@@ -1,22 +1,18 @@
-# .readthedocs.yaml
 # Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
 
-# Required
 version: 2
 
-# Set the version of Python and other tools you might need
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
+  apt_packages:
+    - doxygen
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/conf.py
+mkdocs:
+  configuration: mkdocs.yml
 
-# We recommend specifying your dependencies to enable reproducible builds:
-# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
   install:
-  - requirements: docs/requirements.txt
+    - requirements: docs/requirements.txt

.vscode/settings.json

@@ -15,5 +15,68 @@
   "sonarlint.connectedMode.project": {
     "connectionId": "fastcode",
     "projectKey": "Fastcode_NUClear"
+  },
+  "files.associations": {
+    "__bit_reference": "cpp",
+    "__config": "cpp",
+    "__hash_table": "cpp",
+    "__locale": "cpp",
+    "__node_handle": "cpp",
+    "__split_buffer": "cpp",
+    "__threading_support": "cpp",
+    "__tree": "cpp",
+    "__verbose_abort": "cpp",
+    "array": "cpp",
+    "bitset": "cpp",
+    "cctype": "cpp",
+    "charconv": "cpp",
+    "clocale": "cpp",
+    "cmath": "cpp",
+    "complex": "cpp",
+    "condition_variable": "cpp",
+    "csignal": "cpp",
+    "cstdarg": "cpp",
+    "cstddef": "cpp",
+    "cstdint": "cpp",
+    "cstdio": "cpp",
+    "cstdlib": "cpp",
+    "cstring": "cpp",
+    "ctime": "cpp",
+    "cwchar": "cpp",
+    "cwctype": "cpp",
+    "deque": "cpp",
+    "execution": "cpp",
+    "fstream": "cpp",
+    "future": "cpp",
+    "initializer_list": "cpp",
+    "iomanip": "cpp",
+    "ios": "cpp",
+    "iosfwd": "cpp",
+    "iostream": "cpp",
+    "istream": "cpp",
+    "limits": "cpp",
+    "list": "cpp",
+    "locale": "cpp",
+    "map": "cpp",
+    "mutex": "cpp",
+    "new": "cpp",
+    "optional": "cpp",
+    "ostream": "cpp",
+    "ratio": "cpp",
+    "regex": "cpp",
+    "set": "cpp",
+    "sstream": "cpp",
+    "stack": "cpp",
+    "stdexcept": "cpp",
+    "streambuf": "cpp",
+    "string": "cpp",
+    "string_view": "cpp",
+    "tuple": "cpp",
+    "typeindex": "cpp",
+    "typeinfo": "cpp",
+    "unordered_map": "cpp",
+    "variant": "cpp",
+    "vector": "cpp",
+    "algorithm": "cpp"
   }
 }

CMakeLists.txt

@@ -81,11 +81,13 @@ if(CI_BUILD)
   endif()
 endif(CI_BUILD)
 
+# Tests must be declared before src/ so NUClear can expose test-only APIs when enabled.
+option(BUILD_TESTS "Builds all of the NUClear unit tests." ON)
+
 # Add the src directory
 add_subdirectory(src)
 
 # Add the tests directory
-option(BUILD_TESTS "Builds all of the NUClear unit tests." ON)
 if(BUILD_TESTS)
   enable_testing()
   add_subdirectory(tests)

cmake/TestRunner.cmake

@@ -54,7 +54,8 @@ foreach(target ${all_targets})
   list(APPEND report_outputs ${junit_report_file})
   add_custom_command(
     OUTPUT ${junit_report_file} ${raw_coverage}
-    COMMAND ${command_prefix} $<TARGET_FILE:${target}> --reporter console --reporter JUnit::out=${junit_report_file}
+    COMMAND ${command_prefix} $<TARGET_FILE:${target}> --allow-running-no-tests --reporter console
+            --reporter JUnit::out=${junit_report_file}
     WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
     DEPENDS ${target}
     USES_TERMINAL