squared-netizen · squared-netizen · Aug 21, 2026 · Aug 20, 2026 · Aug 20, 2026
diff --git a/.clang-format b/.clang-format
@@ -0,0 +1,87 @@
+Language: Cpp
+Standard: c++20
+BasedOnStyle: LLVM
+
+IndentWidth: 4
+TabWidth: 4
+UseTab: Never
+ContinuationIndentWidth: 4
+IndentCaseLabels: true
+IndentPPDirectives: BeforeHash
+NamespaceIndentation: None
+AccessModifierOffset: -4
+IndentRequiresClause: true
+RequiresClausePosition: OwnLine
+
+ColumnLimit: 100
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterCaseLabel: false
+  AfterClass: false
+  AfterControlStatement: Never
+  AfterEnum: false
+  AfterFunction: true
+  AfterNamespace: false
+  AfterStruct: false
+  AfterUnion: false
+  BeforeCatch: false
+  BeforeElse: false
+  BeforeLambdaBody: false
+  BeforeWhile: false
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: false
+AllowShortFunctionsOnASingleLine: Empty
+AllowShortIfStatementsOnASingleLine: WithoutElse
+AllowShortLoopsOnASingleLine: false
+AllowShortBlocksOnASingleLine: Never
+AllowShortLambdasOnASingleLine: Inline
+AlwaysBreakTemplateDeclarations: Yes
+BreakConstructorInitializers: BeforeColon
+BreakBeforeBinaryOperators: NonAssignment
+BreakBeforeConceptDeclarations: Always
+PackConstructorInitializers: NextLine
+InsertNewlineAtEOF: true
+SeparateDefinitionBlocks: Always
+
+DerivePointerAlignment: false
+PointerAlignment: Left
+ReferenceAlignment: Left
+QualifierAlignment: Left
+
+SpaceAfterCStyleCast: true
+SpaceBeforeParens: ControlStatements
+SpacesInAngles: Never
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeRangeBasedForLoopColon: true
+
+SortIncludes: CaseSensitive
+IncludeBlocks: Regroup
+IncludeCategories:
+  - Regex: '^<[a-z_]+>$'
+    Priority: 1
+  - Regex: '^<SDL.*\.h>$'
+    Priority: 2
+  - Regex: '^<(lua|lauxlib|lualib)\.h>$'
+    Priority: 3
+  - Regex: '^<.*\.h>$'
+    Priority: 4
+  - Regex: '^<squared/'
+    Priority: 5
+  - Regex: '^"[^"]+"$'
+    Priority: 6
+  - Regex: '.*'
+    Priority: 7
+
+AlignConsecutiveAssignments: None
+AlignConsecutiveDeclarations: None
+AlignTrailingComments: true
+AlignAfterOpenBracket: Align
+
+FixNamespaceComments: true
+SpaceAroundPointerQualifiers: Default
+BitFieldColonSpacing: Both
+Cpp11BracedListStyle: true
+IntegerLiteralSeparator:
+  Decimal: 0
+  Hex: -1
diff --git a/.clang-tidy b/.clang-tidy
@@ -0,0 +1,80 @@
+Checks: >
+  -*,
+  bugprone-*,
+  cert-*,
+  clang-analyzer-*,
+  concurrency-*,
+  cppcoreguidelines-*,
+  misc-*,
+  modernize-*,
+  performance-*,
+  portability-*,
+  readability-*,
+  -bugprone-easily-swappable-parameters,
+  -cert-err33-c,
+  -cppcoreguidelines-avoid-c-arrays,
+  -cppcoreguidelines-avoid-magic-numbers,
+  -cppcoreguidelines-avoid-non-const-global-variables,
+  -cppcoreguidelines-pro-bounds-pointer-arithmetic,
+  -cppcoreguidelines-pro-type-reinterpret-cast,
+  -cppcoreguidelines-pro-type-vararg,
+  -misc-const-correctness,
+  -misc-include-cleaner,
+  -misc-no-recursion,
+  -misc-non-private-member-variables-in-classes,
+  -modernize-avoid-c-arrays,
+  -modernize-use-trailing-return-type,
+  -performance-enum-size,
+  -portability-avoid-pragma-once,
+  -readability-braces-around-statements,
+  -readability-identifier-length,
+  -readability-implicit-bool-conversion,
+  -readability-magic-numbers,
+  -readability-named-parameter,
+  -readability-uppercase-literal-suffix
+
+WarningsAsErrors: '*'
+HeaderFilterRegex: '(^|/)(app/src/main/cpp|include|src|modules)/.*\.(h|hpp|hxx)$'
+ExcludeHeaderFilterRegex: '(^|/)(build|external|third_party|vendor)/'
+FormatStyle: file
+UseColor: true
+
+CheckOptions:
+  - key: readability-identifier-naming.NamespaceCase
+    value: lower_case
+  - key: readability-identifier-naming.ClassCase
+    value: CamelCase
+  - key: readability-identifier-naming.StructCase
+    value: CamelCase
+  - key: readability-identifier-naming.TemplateParameterCase
+    value: CamelCase
+  - key: readability-identifier-naming.FunctionCase
+    value: lower_case
+  - key: readability-identifier-naming.VariableCase
+    value: lower_case
+  - key: readability-identifier-naming.PrivateMemberSuffix
+    value: '_'
+  - key: readability-identifier-naming.ProtectedMemberSuffix
+    value: '_'
+  - key: readability-identifier-naming.EnumCase
+    value: CamelCase
+  - key: readability-identifier-naming.EnumConstantCase
+    value: CamelCase
+  - key: readability-identifier-naming.MacroDefinitionCase
+    value: UPPER_CASE
+  - key: modernize-use-nullptr.NullMacros
+    value: 'NULL'
+  - key: modernize-loop-convert.MaxCopySize
+    value: '16'
+  - key: modernize-pass-by-value.IncludeStyle
+    value: google
+  - key: readability-function-cognitive-complexity.Threshold
+    value: '35'
+  - key: readability-function-size.LineThreshold
+    value: '150'
+  - key: readability-function-size.StatementThreshold
+    value: '200'
+  - key: performance-move-const-arg.CheckTriviallyCopyableMove
+    value: 'true'
+  - key: cppcoreguidelines-special-member-functions.AllowSoleDefaultDtor
+    value: 'true'
diff --git a/.github/workflows/clang-quality.yml b/.github/workflows/clang-quality.yml
@@ -0,0 +1,46 @@
+name: Clang Quality Audit
+
+'on':
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  clang-quality:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+
+    steps:
+      - name: Check out project
+        uses: actions/checkout@v5
+
+      - name: Install Clang workflow tools
+        shell: bash
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install --yes clang clang-format clang-tidy clang-tools fish fd-find ninja-build
+          sudo ln -sf "$(command -v fdfind)" /usr/local/bin/fd
+
+      - name: Configure compilation database
+        shell: bash
+        run: |
+          set -euo pipefail
+          cmake -S . -B build -G Ninja \
+            -DCMAKE_BUILD_TYPE=Debug \
+            -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+
+      - name: Build and test
+        shell: bash
+        run: |
+          set -euo pipefail
+          cmake --build build --parallel 2
+          ctest --test-dir build --output-on-failure
+
+      - name: Run full Clang quality audit
+        continue-on-error: true
+        shell: bash
+        run: fish tools/clang-check.fish --full
diff --git a/AGENTS.md b/AGENTS.md
@@ -180,3 +180,20 @@ command and reason. Never claim a test passed without its output.
 - End with changed files, tests run, failures, warnings, and package-version
   consequences.
 
+<!-- squared-clang-policy:begin -->
+## Mandatory Clang workflow
+
+This package inherits the repository-root `.clang-format`, `.clang-tidy`, and `AGENTS.md`.
+Whenever project-owned C or C++ files in this package change, agents must configure a compilation
+database and run narrow formatter and Clang-Tidy checks on touched files when practical. The
+repository-wide `tools/clang-check.fish --full` audit runs in GitHub Actions and reports existing
+baseline debt. It must run for releases, package-version milestones, public API changes, and broad
+refactors, but remains advisory until the repository-wide baseline is clean.
+
+New warnings in files touched by the task are actionable failures. Existing unrelated baseline
+debt does not block an otherwise successful build or task. Agents must report narrow-check results
+and the latest CI audit result. Missing tools or compilation commands must be reported rather than
+silently skipped. Global warning suppression is forbidden; any necessary suppression must be
+narrow, justified, documented, and reported. Generated, vendored, and third-party source remains
+excluded unless explicitly owned by the task.
+<!-- squared-clang-policy:end -->
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,8 @@
 
 ## Unreleased
 
+- Add repository-wide Clang formatting, Clang-Tidy, Static Analyzer, and GitHub Actions quality gates. Package agent policies inherit the root configuration without changing immutable package content.
+
 - Advance GUI to `0.6.0-dev.15` with determinate progress bars, lifetime-safe
   button groups and radio behavior, drawable-or-glyph button content, imported
   libGDX progress styles, portable tests, documentation, and showcase coverage.

diff --git a/README.md b/README.md
@@ -61,6 +61,10 @@ edge/corner resizing, minimum sizes, and viewport constraints. Its packaged
 skin fixture uses CC0 Kenney UI Pack images and libGDX-compatible split and
 padding metadata.
 
+## Clang quality
+
+GitHub Actions performs repository-wide clang-format, Clang-Tidy, and Clang Static Analyzer checks. Full local execution is optional on constrained Termux devices. Agents must run narrow checks when practical and treat the GitHub quality gate as authoritative.
+
 ## Build packages
 
 Package sources retain the public layout consumed by Squared Project

diff --git a/packages/squared-application/AGENTS.md b/packages/squared-application/AGENTS.md
@@ -79,3 +79,20 @@ results, warnings, and anything that could not run. Before any package version
 change, present the immutable-version and downstream-coordinate impact to the
 user.
 
+<!-- squared-clang-policy:begin -->
+## Mandatory Clang workflow
+
+This package inherits the repository-root `.clang-format`, `.clang-tidy`, and `AGENTS.md`.
+Whenever project-owned C or C++ files in this package change, agents must configure a compilation
+database and run narrow formatter and Clang-Tidy checks on touched files when practical. The
+repository-wide `tools/clang-check.fish --full` audit runs in GitHub Actions and reports existing
+baseline debt. It must run for releases, package-version milestones, public API changes, and broad
+refactors, but remains advisory until the repository-wide baseline is clean.
+
+New warnings in files touched by the task are actionable failures. Existing unrelated baseline
+debt does not block an otherwise successful build or task. Agents must report narrow-check results
+and the latest CI audit result. Missing tools or compilation commands must be reported rather than
+silently skipped. Global warning suppression is forbidden; any necessary suppression must be
+narrow, justified, documented, and reported. Generated, vendored, and third-party source remains
+excluded unless explicitly owned by the task.
+<!-- squared-clang-policy:end -->
diff --git a/packages/squared-backend-sdl2-opengl/AGENTS.md b/packages/squared-backend-sdl2-opengl/AGENTS.md
@@ -80,3 +80,20 @@ results, warnings, and anything that could not run. Before any package version
 change, present the immutable-version and downstream-coordinate impact to the
 user.
 
+<!-- squared-clang-policy:begin -->
+## Mandatory Clang workflow
+
+This package inherits the repository-root `.clang-format`, `.clang-tidy`, and `AGENTS.md`.
+Whenever project-owned C or C++ files in this package change, agents must configure a compilation
+database and run narrow formatter and Clang-Tidy checks on touched files when practical. The
+repository-wide `tools/clang-check.fish --full` audit runs in GitHub Actions and reports existing
+baseline debt. It must run for releases, package-version milestones, public API changes, and broad
+refactors, but remains advisory until the repository-wide baseline is clean.
+
+New warnings in files touched by the task are actionable failures. Existing unrelated baseline
+debt does not block an otherwise successful build or task. Agents must report narrow-check results
+and the latest CI audit result. Missing tools or compilation commands must be reported rather than
+silently skipped. Global warning suppression is forbidden; any necessary suppression must be
+narrow, justified, documented, and reported. Generated, vendored, and third-party source remains
+excluded unless explicitly owned by the task.
+<!-- squared-clang-policy:end -->
diff --git a/packages/squared-data/AGENTS.md b/packages/squared-data/AGENTS.md
@@ -79,3 +79,20 @@ results, warnings, and anything that could not run. Before any package version
 change, present the immutable-version and downstream-coordinate impact to the
 user.
 
+<!-- squared-clang-policy:begin -->
+## Mandatory Clang workflow
+
+This package inherits the repository-root `.clang-format`, `.clang-tidy`, and `AGENTS.md`.
+Whenever project-owned C or C++ files in this package change, agents must configure a compilation
+database and run narrow formatter and Clang-Tidy checks on touched files when practical. The
+repository-wide `tools/clang-check.fish --full` audit runs in GitHub Actions and reports existing
+baseline debt. It must run for releases, package-version milestones, public API changes, and broad
+refactors, but remains advisory until the repository-wide baseline is clean.
+
+New warnings in files touched by the task are actionable failures. Existing unrelated baseline
+debt does not block an otherwise successful build or task. Agents must report narrow-check results
+and the latest CI audit result. Missing tools or compilation commands must be reported rather than
+silently skipped. Global warning suppression is forbidden; any necessary suppression must be
+narrow, justified, documented, and reported. Generated, vendored, and third-party source remains
+excluded unless explicitly owned by the task.
+<!-- squared-clang-policy:end -->
diff --git a/packages/squared-graphics/AGENTS.md b/packages/squared-graphics/AGENTS.md
@@ -79,3 +79,20 @@ results, warnings, and anything that could not run. Before any package version
 change, present the immutable-version and downstream-coordinate impact to the
 user.
 
+<!-- squared-clang-policy:begin -->
+## Mandatory Clang workflow
+
+This package inherits the repository-root `.clang-format`, `.clang-tidy`, and `AGENTS.md`.
+Whenever project-owned C or C++ files in this package change, agents must configure a compilation
+database and run narrow formatter and Clang-Tidy checks on touched files when practical. The
+repository-wide `tools/clang-check.fish --full` audit runs in GitHub Actions and reports existing
+baseline debt. It must run for releases, package-version milestones, public API changes, and broad
+refactors, but remains advisory until the repository-wide baseline is clean.
+
+New warnings in files touched by the task are actionable failures. Existing unrelated baseline
+debt does not block an otherwise successful build or task. Agents must report narrow-check results
+and the latest CI audit result. Missing tools or compilation commands must be reported rather than
+silently skipped. Global warning suppression is forbidden; any necessary suppression must be
+narrow, justified, documented, and reported. Generated, vendored, and third-party source remains
+excluded unless explicitly owned by the task.
+<!-- squared-clang-policy:end -->
diff --git a/packages/squared-graphics2d/AGENTS.md b/packages/squared-graphics2d/AGENTS.md
@@ -80,3 +80,20 @@ results, warnings, and anything that could not run. Before any package version
 change, present the immutable-version and downstream-coordinate impact to the
 user.
 
+<!-- squared-clang-policy:begin -->
+## Mandatory Clang workflow
+
+This package inherits the repository-root `.clang-format`, `.clang-tidy`, and `AGENTS.md`.
+Whenever project-owned C or C++ files in this package change, agents must configure a compilation
+database and run narrow formatter and Clang-Tidy checks on touched files when practical. The
+repository-wide `tools/clang-check.fish --full` audit runs in GitHub Actions and reports existing
+baseline debt. It must run for releases, package-version milestones, public API changes, and broad
+refactors, but remains advisory until the repository-wide baseline is clean.
+
+New warnings in files touched by the task are actionable failures. Existing unrelated baseline
+debt does not block an otherwise successful build or task. Agents must report narrow-check results
+and the latest CI audit result. Missing tools or compilation commands must be reported rather than
+silently skipped. Global warning suppression is forbidden; any necessary suppression must be
+narrow, justified, documented, and reported. Generated, vendored, and third-party source remains
+excluded unless explicitly owned by the task.
+<!-- squared-clang-policy:end -->
diff --git a/packages/squared-gui-file-picker/AGENTS.md b/packages/squared-gui-file-picker/AGENTS.md
@@ -10,3 +10,21 @@ Run the file-picker host test, package documentation test, full CMake workflow,
 Doxygen, Graphviz validation, and package build verification before release.
 Never overwrite an immutable `.sq` coordinate or stage/publish without explicit
 authorization.
+
+<!-- squared-clang-policy:begin -->
+## Mandatory Clang workflow
+
+This package inherits the repository-root `.clang-format`, `.clang-tidy`, and `AGENTS.md`.
+Whenever project-owned C or C++ files in this package change, agents must configure a compilation
+database and run narrow formatter and Clang-Tidy checks on touched files when practical. The
+repository-wide `tools/clang-check.fish --full` audit runs in GitHub Actions and reports existing
+baseline debt. It must run for releases, package-version milestones, public API changes, and broad
+refactors, but remains advisory until the repository-wide baseline is clean.
+
+New warnings in files touched by the task are actionable failures. Existing unrelated baseline
+debt does not block an otherwise successful build or task. Agents must report narrow-check results
+and the latest CI audit result. Missing tools or compilation commands must be reported rather than
+silently skipped. Global warning suppression is forbidden; any necessary suppression must be
+narrow, justified, documented, and reported. Generated, vendored, and third-party source remains
+excluded unless explicitly owned by the task.
+<!-- squared-clang-policy:end -->