Merge branch 'develop' of https://github.com/makr-code/ThemisDB into tmp/push-fix3

Author: makr-code

.github/ISSUE_TEMPLATE/docs_audit.md

@@ -67,6 +67,7 @@ Describe what the documentation should say or cover after fixing this issue.
 - [ ] Issue is assigned to the correct docs milestone
 - [ ] Release-gate evidence is linked when the SOT domain is `build-test` or `release-versioning`
 - [ ] Private-plugin findings do not leak confidential repository paths, URLs, or implementation details into public docs
+- [ ] If AI coding context is affected: `AI_WIKI_INTEGRATION_PLAYBOOK.md` and `ai_context/developer_llm_wiki/*` references are reviewed for sync and drift
 
 ## Additional Context
 

.github/PR_LABELING_GOVERNANCE.md

@@ -69,6 +69,9 @@ Labels indicating release or quality status.
 | `release_critical` | Changes to release-critical modules (Wave A focus areas) |
 | `ai-generated` | Changes generated by AI/Copilot (ai_working/) |
 | `breaking-change` | (AI-detected) Contains breaking changes |
+| `quality/doxygen-failed` | Doxygen governance gate failed on changed public APIs |
+| `quality/doxygen-warning` | Doxygen gate warning or waived Tier-1 coverage shortfall |
+| `governance/doxygen-waiver` | Approved temporary waiver marker for Tier-1 Doxygen coverage escalation |
 | `severity:critical` | (AI-detected) Critical severity impact |
 | `severity:high` | (AI-detected) High severity impact |
 | `severity:medium` | (AI-detected) Medium severity impact |
@@ -156,6 +159,15 @@ Detected classifications are converted to labels and merged with existing labels
 - **Gracefully degrades** if AI inference fails or returns invalid JSON
 - Safe to disable by removing the job
 
+### Workflow-driven Doxygen gate labeling
+
+- Triggered by `.github/workflows/gate-pr-doxygen-governance.yml`
+- Waiver approvals for `T1-DOXYGEN-COVERAGE` are issued by `.github/workflows/compliance-governance-gates.yml` from PR comments and then re-validated by the PR gate
+- Uses `.github/actions/status-flags-and-issues` for idempotent PR comments and label state
+- `quality/doxygen-failed` is the canonical blocker label for missing Doxygen structure, warning-log failures, or missing XML generation in scoped code changes
+- `quality/doxygen-warning` is used for advisory `@throws`/`@tparam` findings, non-blocking observation, and waived coverage shortfalls
+- `governance/doxygen-waiver` is not path-based; it is a workflow-synchronized governance marker that reflects an active PR comment approval for `T1-DOXYGEN-COVERAGE`
+
 ## Maintenance and Updates
 
 ### When to Update Labels

.github/WORKFLOW_GUIDELINES.md

@@ -6,7 +6,7 @@ Die kanonische Liste aktiver Workflows steht in `.github/WORKFLOW_REGISTRY.md`.
 Workflows unter `.github/no_workflows/` gelten als bewusst deaktivierte Quarantaene und
 duerfen nicht stillschweigend reaktiviert werden.
 
-## Aktive Workflows (39)
+## Aktive Workflows (40)
 Die aktuelle kanonische Liste steht in `.github/WORKFLOW_REGISTRY.md`; der alte 21er-Stand war veraltet und wird hier durch den aktuellen, im Repository geltenden Zustand ersetzt.
 
 Kernliste der aktiven Workflows:
@@ -20,6 +20,7 @@ Kernliste der aktiven Workflows:
 - `.github/workflows/build-content-regression.yml`
 - `.github/workflows/build-llm-inference.yml`
 - `.github/workflows/gate-pr-core.yml`
+- `.github/workflows/gate-pr-doxygen-governance.yml`
 - `.github/workflows/release-build-matrix.yml`
 - `.github/workflows/release-mainline.yml`
 - `.github/workflows/build-widget.yml`
@@ -101,7 +102,7 @@ Archiviert in `.github/no_workflows/` (im Zuge Workflow Framework Refactoring):
 - Publish-Workflows nur ueber Tag- oder Environment-Gates freigeben.
 - Third-party Actions auf immutable Commit-SHAs pinnen (SHA-only, kein `@vX.Y.Z` Tag als einzige Referenz).
   Beispiel: `uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2`
-  Enforcement: `actionlint` + SHA-Pin-Prüfung in `quality-static-analysis.yml`.
+  Enforcement: `gate-pr-core.yml` Preflight-Checks + lokales `actionlint` via `scripts/test-github-actions-local.ps1`.
 - Compliance-Gates fuer Dependencies muessen branch- und pfadbegrenzt sein und ein downloadbares Audit-Artefakt erzeugen.
 - OIDC-basierte Authentifizierung (kein long-lived PAT) fuer ghcr.io und neue Registry-Ziele.
 
@@ -250,8 +251,11 @@ Damit bleiben Ergebnisse reproduzierbar und lassen sich nach dem Lauf mit
 
 ## Doxygen Coverage Threshold (Maintainer)
 - Der Doxygen-Coverage-Gate liest den Schwellwert zentral aus `.github/ci-scope-config.yaml` unter `quality_gates.docs_coverage_threshold`.
-- Standardwert ist `90`.
-- Empfohlene stufenweise Anhebung: `90 -> 92 -> 95`.
+- Kanonische CI-Konfiguration ist `Doxyfile.audit`; der PR-Gate-Workflow verwendet eine daraus abgeleitete, modul-scoped Laufkonfiguration.
+- Aktueller Standardwert ist `95`.
+- Empfohlene stufenweise Anhebung ab diesem Stand: `95 -> 97 -> 99`.
+- Strukturfehler (`@brief`, `@param`, `@return`, fehlender Doxygen-Block, Doxygen-Warnungen, fehlendes XML`) sind im PR-Gate blocking; Coverage < Threshold ist auf `develop` beobachtbar und auf Release-/Phase-6-Scope eskalationspflichtig.
+- Ein genehmigter Tier-1-Override fuer `T1-DOXYGEN-COVERAGE` muss ueber `.github/workflows/compliance-governance-gates.yml` per `/approve-with-waiver ...` kommentarbasiert freigegeben werden; `gate-pr-doxygen-governance.yml` wertet dazu den kanonischen PR-Kommentar-Marker aus und synchronisiert das Label `governance/doxygen-waiver`.
 - Nach jeder Anhebung zuerst mehrere PR-Laeufe beobachten und nur bei stabiler Signalqualitaet weiter erhoehen.
 - Bei hoher False-Positive-Rate den Schwellwert voruebergehend zuruecksetzen und Doku-Luecken gezielt abbauen.
 

.github/WORKFLOW_REGISTRY.md

@@ -19,6 +19,8 @@ Quarantaene, nicht einen inoffiziellen Reservepool fuer schnelle Reaktivierung.
 ### Fokus-Workflows
 - `.github/workflows/gate-pr-core.yml`
   — Fast PR-Gate-Layer inkl. `release-critical-tests` (mandatory), Boundary- und Policy-Gates
+- `.github/workflows/gate-pr-doxygen-governance.yml`
+  — PR-Gate fuer geaenderten C/C++-Sourcecode: GS3-Doxygen-Strukturpruefung, Doxygen-Audit-Warnungen, XML-Generierbarkeit, Coverage-/Waiver-Eskalation
 - `.github/workflows/build-mainline.yml`
   — Multi-OS Build/Test-Matrix inkl. optionaler Sanitizer-Lane per `workflow_dispatch`
 - `.github/workflows/release-mainline.yml`
@@ -37,8 +39,6 @@ Quarantaene, nicht einen inoffiziellen Reservepool fuer schnelle Reaktivierung.
   — SBOM-/Signatur-/Release-Compliance-Pruefungen
 - `.github/workflows/security-codeql.yml`
   — CodeQL Analyse-Workflow
-- `.github/workflows/quality-static-analysis.yml`
-  — Statische Qualitaetspruefungen und Artefaktberichte
 - `.github/workflows/compliance-governance-gates.yml`
   — Governance- und Release-Policy-Gates
 - `.github/workflows/maintenance-docs.yml`

.github/actions/setup-cpp-build/action.yml

@@ -36,7 +36,12 @@ runs:
     - name: Pre-configure sccache environment
       shell: bash
       run: |
-        echo "SCCACHE_GHA_ENABLED=true" >> "$GITHUB_ENV"
+        # Honor caller overrides (for example SCCACHE_GHA_ENABLED=false in
+        # release-critical gating jobs). Default to GHA backend only when the
+        # caller did not set an explicit value.
+        if [ -z "${SCCACHE_GHA_ENABLED:-}" ]; then
+          echo "SCCACHE_GHA_ENABLED=true" >> "$GITHUB_ENV"
+        fi
         # Ignore transient cache I/O errors so sccache falls back to direct
         # compilation instead of aborting with exit code 2.
         echo "SCCACHE_IGNORE_SERVER_IO_ERROR=1" >> "$GITHUB_ENV"

.github/actions/status-flags-and-issues/action.yml

@@ -139,6 +139,9 @@ runs:
             'status/build-pending': '0075CA',
             'scanner/gs3': '1D76DB',
             'scanner/runtime': '1D76DB',
+            'quality/doxygen-failed': 'B60205',
+            'quality/doxygen-warning': 'FBCA04',
+            'governance/doxygen-waiver': 'FBCA04',
             security: 'B60205',
             'security/critical': 'B60205',
           };

.github/branch-protection-rules.json

@@ -154,6 +154,7 @@
     "test-integration": "Integration test suite",
     "test-performance": "Performance/benchmark tests",
     "static-analysis": "Static analysis (clang-tidy, cppcheck)",
+    "Doxygen Governance": "Doxygen source-governance gate for changed public C/C++ APIs",
     "security-scan": "CodeQL security scanning",
     "validate-ai-guardrails": "AI-Guardrails validation workflow",
     "validate-roadmap": "Roadmap structure validation"
@@ -165,6 +166,7 @@
     "Review protection rules quarterly for effectiveness",
     "Commit signing (GPG) is required for main and release/* branches",
     "Roadmap validation (validate-roadmap) is required before merge on all protected branches",
+    "Add the 'Doxygen Governance' required check to protected branches that enforce source-governance before merge",
     "Code owner review is required for main and release/* branches",
     "Restricted push access on main and release/* to @makr-code/maintainers team"
   ]

.github/ci-scope-config.yaml

@@ -155,11 +155,11 @@ workflow_scope_map:
   ci-benchmarks:                [has_llm_changes, has_acceleration_changes, has_gpu_changes]
   copilot-ollama-router-ci:     [has_code_changes]
   copilot-regression-guard:     [has_code_changes, has_config_changes]
-  quality-static-analysis:      [has_code_changes, has_config_changes]
+  gate-pr-doxygen-governance:   [has_code_changes, has_config_changes]
 
 # ── Quality gate tuning ─────────────────────────────────────────────────────
 # Maintainer knob for Doxygen XML coverage threshold used by
-# .github/workflows/quality-static-analysis.yml (doxygen-coverage job).
+# .github/workflows/gate-pr-doxygen-governance.yml.
 # Increase gradually (recommended): 95 -> 97 -> 99.
 # Raised to 95 after @brief coverage improvement (Classes: 99.9%, 2026-08-12).
 quality_gates:

.github/codeql/codeql-config.yml

@@ -0,0 +1,44 @@
+# CodeQL Advanced Configuration for ThemisDB
+#
+# Reduces database build time and size by excluding vendored/third-party paths
+# and generated artefacts. Only production source under src/, include/,
+# tests/, benchmarks/, and tools/ is analysed.
+#
+# Reference: https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning
+
+name: "ThemisDB CodeQL Config"
+
+# ── Query suites ──────────────────────────────────────────────────────────────
+# The active query suite is selected by the workflow via the `queries:` input
+# on the `github/codeql-action/analyze` step:
+#   PR / push   → security-extended  (security-relevant rules, no quality gates)
+#   scheduled   → security-and-quality  (full suite, runs weekly off-hours)
+
+# ── Path exclusions ───────────────────────────────────────────────────────────
+# Excluded paths are NOT compiled into the CodeQL database, which reduces
+# database size and analysis time significantly for this repo.
+paths-ignore:
+  # Vendored / third-party submodules
+  - vcpkg
+  - llama.cpp
+  - internal
+
+  # Generated build artefacts
+  - build
+  - build-*
+  - out
+
+  # Test-only tooling and helper scripts (not production surface)
+  - tools/tests
+  - scripts
+
+  # Documentation and configuration files only
+  - docs
+  - ai_context
+  - ai_working
+  - audit
+  - security
+
+  # Package / distribution staging
+  - dist
+  - packages

.github/copilot-instructions.md

@@ -13,6 +13,47 @@ Pflichtregeln:
 3. Änderungen, die Architektur, Betrieb, Prozesse oder Governance betreffen, müssen die zugehörigen Wiki-Inhalte synchron halten.
 4. Fehlende Wiki-Inhalte sind als Lücke zu melden und in den Arbeitsartefakten/PR-Hinweisen zu markieren statt stillschweigend zu ignorieren.
 
+## 0.1) Developer LLM Wiki fuer GitHub Copilot auf GitHub (MUST)
+
+Wenn GitHub Copilot als Coding Agent auf GitHub implementiert, reviewt oder refactort, muss es das Developer LLM Wiki aktiv als Vibe-Coding-Kontext nutzen.
+
+Pflichtablauf:
+
+1. Zuerst `AI_WIKI_INTEGRATION_PLAYBOOK.md` lesen.
+2. Vor Codeaenderungen die relevanten Developer-Wiki-Artefakte aus `ai_context/developer_llm_wiki/` konsultieren:
+   - `INDEX.md`
+   - `MODULES_AND_APIS.md`
+   - `BUILD_TEST_CI_AND_OPERATIONS.md`
+   - `GOVERNANCE_AND_ROADMAP.md`
+3. `ai_context/developer_llm_wiki/WIKI_STATUS.json` als Frische-/Health-Signal pruefen (`generated_at`, `source_count`, Delta-Status).
+4. Wiki-Kontext nach Task-Typ priorisieren:
+   - API-/Modularbeit → `MODULES_AND_APIS.md`
+   - Build/CI/Test → `BUILD_TEST_CI_AND_OPERATIONS.md`
+   - Governance/Roadmap/Release → `GOVERNANCE_AND_ROADMAP.md`
+   - C/C++-Implementierung → `MODULES_AND_APIS.md` plus `memory_management_policy.md`, `OOP_AND_SOC_PRINCIPLES.md`, `FUNCTION_CLASSIFICATION.md`
+   - allgemeiner Einstieg/Link-Hub → `INDEX.md`
+5. Bei Konflikten gilt: Root-SOT und Modulquellen vor kompilierter Wiki-Synthese.
+6. Wenn Wiki-Artefakte fehlen, stale wirken oder der Aufgabe widersprechen, diese Luecke explizit nennen statt das Wiki still zu ignorieren.
+
+Task-spezifische Mindestregeln:
+
+- API-/Modularbeit: zuerst `ai_context/developer_llm_wiki/MODULES_AND_APIS.md`, danach relevante `ai_context/api_contracts/*.md` und modulnahe `src/<module>/*.md`.
+- Build/CI/Test: zuerst `ai_context/developer_llm_wiki/BUILD_TEST_CI_AND_OPERATIONS.md`; bei Fehlern zusaetzlich immer konkrete GitHub-Actions-Logs und betroffene Workflow-Dateien pruefen.
+- Governance/Roadmap/Release: zuerst `ai_context/developer_llm_wiki/GOVERNANCE_AND_ROADMAP.md`, danach Root-SOT-Dateien (`ROADMAP.md`, `FUTURE_ENHANCEMENTS.md`, `RELEASE_STRATEGY.md`, `BRANCHING_STRATEGY.md`, `VERSIONING.md`).
+- C/C++-Arbeit: zuerst `ai_context/developer_llm_wiki/MODULES_AND_APIS.md`, danach `ai_context/memory_management_policy.md`, `ai_context/OOP_AND_SOC_PRINCIPLES.md`, `ai_context/FUNCTION_CLASSIFICATION.md` sowie die einschlaegigen `.github/instructions/*cpp*` Regeln.
+  - Public API / Header-Vertraege: zusaetzlich zuerst relevante `ai_context/api_contracts/*.md` und Doxygen-/Thread-Safety-/Ownership-Pflichten pruefen.
+  - Internal Core / Implementierungslogik: Ownership, RAII, `detail::`-Grenzen und unbeabsichtigte API-Flaechenerweiterungen gegen `memory_management_policy.md` und `OOP_AND_SOC_PRINCIPLES.md` pruefen.
+  - Concurrency / Performance: Locking, Atomics, Hot-Path-Klassifikation, Timeout/Cancellation und Benchmark-Bezug gegen `FUNCTION_CLASSIFICATION.md` und C++-Best-Practice-Regeln pruefen.
+  - Plugin-Boundaries / Extensibility: Adapter-/Interface-Grenzen sowie Public-vs-Private-Grenzen gegen `OOP_AND_SOC_PRINCIPLES.md` und `GOVERNANCE_AND_ROADMAP.md` pruefen.
+  - Einordnungshilfe:
+    - `include/**` oder externe Vertragsaenderung → Public API
+    - `src/**`, interne Header oder `detail::` → Internal Core
+    - Locking/Atomics/Latenz/Benchmarks/Timeouts → Concurrency / Performance
+    - Plugin-Interfaces/Adapter/Edition-Grenzen → Plugin-Boundaries / Extensibility
+  - Wenn mehrere C++-Subtypen zugleich betroffen sind, gelten alle relevanten Wiki-/Governance-Pflichten kumulativ.
+
+Details und Dateizwecke: [AI_WIKI_CONTEXT.md](copilot/AI_WIKI_CONTEXT.md)
+
 ## 1) Ziel
 
 Roadmap-Einträge müssen so konkret sein, dass Copilot **produktiven Sourcecode** statt Stub/Rumpf erzeugen kann.