AGENTS.md

GitHub Actions workflows for CI, release automation, and policy checks.

Scope

This file governs edits in .github/workflows/*.yml.
Keep one top-level triggered workflow per CI intent:
- feature-ci.yml for non-master push CI
- master-ci.yml for merged-PR-to-master release CI
Keep OS/platform splits in reusable workflows invoked via workflow_call.

feature-ci.yml -> orchestrator for feature branch CI.
feature-linux.yml -> reusable Linux build/test/package workflow.
feature-windows.yml -> reusable Windows build/test/package workflow.
master-pr-title-guard.yml -> validates semantic-prefix policy for PRs targeting master.
master-ci.yml -> orchestrator for merged PRs into master.
master-windows.yml -> reusable Windows build/test/package workflow for master release flow.

Keep workflow intent stable:
- feature workflows produce branch+sha artifacts
- master workflows produce semver-tagged release artifacts
Do not duplicate top-level triggers for the same intent (avoid split runs in Actions UI).
Preserve artifact naming conventions unless docs are updated in the same change:
- ccm3-linux-<version>.zip
- ccm3-windows-<version>.zip
- ccm3-windows-installer-<version> (feature) and .exe (master release asset)
Preserve embedded app version wiring via -DCCM_APP_VERSION=... in both feature and master build flows.
Keep master release flow gated to merged PRs only.
Keep PR title prefix policy aligned with scripts/compute_master_semver.sh.

Prefer minimal, surgical edits; avoid large workflow rewrites unless requested.
Reusable workflows should declare explicit workflow_call inputs for required context (e.g., version, merge SHA).
Sonar coverage steps that use gcovr must exclude third-party build trees at discovery time with --exclude-directories (for example build/_deps) so gcov does not process dependency .gcda files.
The Sonar scan step passes -Dsonar.coverage.exclusions=**/ui_wx/**,**/app/** so the coverage quality gate reflects ccm_core_tests only (wx UI and the composition root are not executed under test). sonar.sources stays core,ui_wx,app; bugs/security/duplications still analyze those trees.
For Linux Sonar coverage jobs, keep compiler and gcov toolchain aligned; because cmake/Toolchain.cmake prefers Clang by default, set -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ explicitly in the coverage configure step when using gcovr default gcov.
Keep permissions least-privilege:
- reusable build workflows: contents: read
- release/tag orchestrator: contents: write
Keep shells consistent with runner setup:
- Linux steps use standard bash-compatible shell.
- Windows MSYS2 jobs keep shell: msys2 {0} and run msys2/setup-msys2 before MSYS2 commands.

After changing workflow topology, update docs/ci-cd-guide.md.
If artifact names or release behavior change, update docs/ci-cd-guide.md and docs/versioning.md if needed.
If semver prefix policy changes, update both master-pr-title-guard.yml and docs.
If adding/removing workflow files, update this file's "Current workflow map".

Do not add a second top-level feature or master trigger file.
Do not move release creation into a reusable workflow that lacks contents: write.
Do not introduce MSVC-specific build commands; project CI targets Clang/MinGW toolchains.
Do not silently change artifact names; downstream release/download steps depend on exact names.