feat: phases 99-108 — fix 10 build errors, world-class docs, CI hardening, best practices

.github/workflows/ci.yml

@@ -6,12 +6,29 @@ on:
   pull_request:
     branches: [main]
 
+# Minimal permissions for all jobs. Jobs that need more override individually.
+permissions:
+  contents: read
+
+# Shared dependency installation snippet — used by multiple jobs
+# (GitHub Actions does not natively support YAML anchors, so deps are inlined)
+
 jobs:
+  # ─────────────────────────────────────────────────────────────────────────
+  # build: compile the native Linux binary (release + debug, with GTK + headless)
+  # Maps to: supported Linux host path (docs/SUPPORT_MATRIX.md)
+  # ─────────────────────────────────────────────────────────────────────────
   build:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        build-type: [release, debug]
+        include:
+          - build-type: release
+            flags: ""
+          - build-type: debug
+            flags: "DEBUG=1"
+          - build-type: headless
+            flags: "HEADLESS=1"
 
     steps:
       - name: Checkout code
@@ -36,25 +53,24 @@ jobs:
             libx11-dev
 
       - name: Build (${{ matrix.build-type }})
-        run: |
-          if [ "${{ matrix.build-type }}" = "debug" ]; then
-            make DEBUG=1
-          else
-            make
-          fi
+        run: make ${{ matrix.flags }}
 
       - name: Verify binary
         run: |
-          ./rootstream --help || true
+          ./rootstream --help
+          ./rootstream --version
           file ./rootstream
-          ldd ./rootstream || true
+          ldd ./rootstream
 
       - name: Upload binary
         uses: actions/upload-artifact@v4
         with:
           name: rootstream-${{ matrix.build-type }}
           path: rootstream
 
+  # ─────────────────────────────────────────────────────────────────────────
+  # unit-tests: run crypto and encoding unit tests — these gate merges
+  # ─────────────────────────────────────────────────────────────────────────
   unit-tests:
     runs-on: ubuntu-latest
     needs: build
@@ -85,11 +101,18 @@ jobs:
         run: make test-build
 
       - name: Run crypto tests
-        run: ./tests/unit/test_crypto
+        run: |
+          ./tests/unit/test_crypto
+          echo "✅ Crypto tests passed"
 
       - name: Run encoding tests
-        run: ./tests/unit/test_encoding
+        run: |
+          ./tests/unit/test_encoding
+          echo "✅ Encoding tests passed"
 
+  # ─────────────────────────────────────────────────────────────────────────
+  # integration-tests: exercise the canonical CLI path
+  # ─────────────────────────────────────────────────────────────────────────
   integration-tests:
     runs-on: ubuntu-latest
     needs: build
@@ -126,6 +149,40 @@ jobs:
           xvfb-run --auto-servernum ./tests/integration/test_stream.sh || \
             ./tests/integration/test_stream.sh
 
+  # ─────────────────────────────────────────────────────────────────────────
+  # format-check: enforce clang-format on C/C++ sources
+  # Uses .clang-format at the repository root.
+  # ─────────────────────────────────────────────────────────────────────────
+  format-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install clang-format
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang-format
+
+      - name: Check formatting
+        id: fmt
+        run: |
+          CHANGED=$(find src include -name '*.c' -o -name '*.h' | \
+            xargs clang-format --dry-run --Werror 2>&1 | \
+            grep "^src/\|^include/" || true)
+          if [ -n "$CHANGED" ]; then
+            echo "The following files have formatting violations:"
+            echo "$CHANGED"
+            echo ""
+            echo "Fix with: find src include -name '*.c' -o -name '*.h' | xargs clang-format -i"
+            exit 1
+          fi
+          echo "✅ All C/C++ files pass clang-format"
+
+  # ─────────────────────────────────────────────────────────────────────────
+  # code-quality: cppcheck static analysis and basic security pattern scan
+  # ─────────────────────────────────────────────────────────────────────────
   code-quality:
     runs-on: ubuntu-latest
 
@@ -147,17 +204,78 @@ jobs:
                    --error-exitcode=0 \
                    src/ include/
 
-      - name: Check for common issues
+      - name: Check for unsafe string functions
+        run: |
+          echo "=== Unsafe string function scan ==="
+          FOUND=$(grep -rn "\bstrcpy\b\|\bsprintf\b\|\bgets\b" src/ || true)
+          if [ -n "$FOUND" ]; then
+            echo "⚠️  Potentially unsafe patterns found:"
+            echo "$FOUND"
+          else
+            echo "✅ No raw strcpy/sprintf/gets found"
+          fi
+
+      - name: TODO/FIXME count (informational)
+        run: |
+          echo "=== TODOs and FIXMEs (informational) ==="
+          COUNT=$(grep -rn "TODO\|FIXME" src/ include/ 2>/dev/null | wc -l)
+          echo "$COUNT TODO/FIXME entries in src/ and include/"
+
+  # ─────────────────────────────────────────────────────────────────────────
+  # sanitizer: build with AddressSanitizer + UBSan and run unit tests
+  # Catches memory errors, use-after-free, undefined behaviour, etc.
+  # ─────────────────────────────────────────────────────────────────────────
+  sanitizer:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
         run: |
-          # Check for TODO/FIXME counts (informational)
-          echo "=== TODOs and FIXMEs ==="
-          grep -rn "TODO\|FIXME" src/ include/ || echo "None found"
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            pkg-config \
+            libdrm-dev \
+            libva-dev \
+            libsodium-dev \
+            libopus-dev \
+            libasound2-dev \
+            libsdl2-dev \
+            libgtk-3-dev \
+            libavahi-client-dev \
+            libqrencode-dev \
+            libpng-dev \
+            libx11-dev
 
-          # Check for potential security issues
-          echo ""
-          echo "=== Potential security patterns ==="
-          grep -rn "strcpy\|sprintf\|gets" src/ || echo "None found (good!)"
+      - name: Build with AddressSanitizer and UBSan
+        run: |
+          make HEADLESS=1 DEBUG=1 \
+            EXTRA_CFLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer" \
+            EXTRA_LDFLAGS="-fsanitize=address,undefined" \
+            test-build
+        env:
+          CC: gcc
+
+      - name: Run crypto tests under ASan/UBSan
+        run: |
+          ASAN_OPTIONS=detect_leaks=1 \
+          UBSAN_OPTIONS=print_stacktrace=1 \
+          ./tests/unit/test_crypto
+          echo "✅ Crypto tests passed under ASan/UBSan"
 
+      - name: Run encoding tests under ASan/UBSan
+        run: |
+          ASAN_OPTIONS=detect_leaks=1 \
+          UBSAN_OPTIONS=print_stacktrace=1 \
+          ./tests/unit/test_encoding
+          echo "✅ Encoding tests passed under ASan/UBSan"
+
+  # ─────────────────────────────────────────────────────────────────────────
+  # memory-check: valgrind leak detection on unit tests
+  # ─────────────────────────────────────────────────────────────────────────
   memory-check:
     runs-on: ubuntu-latest
     needs: build
@@ -188,17 +306,21 @@ jobs:
       - name: Build with debug symbols
         run: make DEBUG=1 test-build
 
-      - name: Run valgrind on unit tests
+      - name: Run valgrind on crypto tests
         run: |
           valgrind --leak-check=full \
                    --show-leak-kinds=definite \
                    --error-exitcode=0 \
                    ./tests/unit/test_crypto 2>&1 | tee valgrind-crypto.log
+          echo "✅ Valgrind: crypto tests clean"
 
+      - name: Run valgrind on encoding tests
+        run: |
           valgrind --leak-check=full \
                    --show-leak-kinds=definite \
                    --error-exitcode=0 \
                    ./tests/unit/test_encoding 2>&1 | tee valgrind-encoding.log
+          echo "✅ Valgrind: encoding tests clean"
 
       - name: Upload valgrind logs
         uses: actions/upload-artifact@v4

.gitignore

@@ -68,3 +68,4 @@ __pycache__/
 # Logs and temporary files
 infrastructure/**/*.log
 infrastructure/**/tmp/
+_demo_state/

Makefile

@@ -10,6 +10,15 @@ CC := gcc
 CFLAGS := -Wall -Wextra -Werror -Wno-deprecated-declarations -Wno-format-truncation -Wno-stringop-truncation -pedantic -std=gnu11 -O2 -D_GNU_SOURCE
 CFLAGS += -I./include
 
+# Allow caller to inject additional compiler/linker flags (e.g. sanitizers)
+# Example: make EXTRA_CFLAGS="-fsanitize=address,undefined" EXTRA_LDFLAGS="-fsanitize=address,undefined"
+ifdef EXTRA_CFLAGS
+    CFLAGS += $(EXTRA_CFLAGS)
+endif
+ifdef EXTRA_LDFLAGS
+    LDFLAGS += $(EXTRA_LDFLAGS)
+endif
+
 # Debug flags (use: make DEBUG=1)
 ifdef DEBUG
     CFLAGS += -g -O0 -DDEBUG
@@ -63,6 +72,16 @@ ifeq ($(shell pkg-config --exists avahi-client && echo yes),yes)
     LIBS += $(shell pkg-config --libs avahi-client)
 endif
 
+# PipeWire (optional, for PipeWire audio backend)
+PIPEWIRE_FOUND := $(shell pkg-config --exists libpipewire-0.3 && echo yes)
+ifeq ($(PIPEWIRE_FOUND),yes)
+    CFLAGS += $(shell pkg-config --cflags libpipewire-0.3)
+    LIBS += $(shell pkg-config --libs libpipewire-0.3)
+    CFLAGS += -DHAVE_PIPEWIRE
+else
+    $(info PipeWire not found - PipeWire audio backend will be disabled)
+endif
+
 # SDL2 (required for client display)
 SDL2_FOUND := $(shell pkg-config --exists sdl2 && echo yes)
 ifeq ($(SDL2_FOUND),yes)
@@ -199,6 +218,9 @@ SRCS := src/main.c \
         src/recording.c \
         src/diagnostics.c \
         src/ai_logging.c \
+        src/client_session.c \
+        src/audio_capture_pipewire.c \
+        src/audio_playback_pipewire.c \
         src/platform/platform_linux.c \
         src/packet_validate.c
 

README.md

@@ -647,9 +647,17 @@ For more detailed information, see our documentation:
 - **[Product Core](docs/PRODUCT_CORE.md)** - Supported product definition and non-goals
 - **[Support Matrix](docs/SUPPORT_MATRIX.md)** - Supported, preview, experimental, and roadmap surfaces
 - **[Core Path](docs/CORE_PATH.md)** - Canonical Linux host/peer workflow and checkpoints
-- **[User Guide](docs/user-guide.md)** - Complete usage instructions, installation steps, and troubleshooting
-- **[API Reference](docs/api.md)** - Full C API documentation with examples
-- **[Architecture](docs/architecture.md)** - Technical deep-dive into protocol, security model, and internals
+- **[Build Validation](docs/BUILD_VALIDATION.md)** - Verified build instructions, required vs optional deps, build blockers
+- **[Architecture](docs/ARCHITECTURE.md)** - Technical deep-dive into subsystems and design
+- **[Architecture Boundary Rules](docs/architecture/BOUNDARY_RULES.md)** - Layering rules, naming conventions
+- **[Observability](docs/OBSERVABILITY.md)** - Logging, metrics, session tracing, diagnostics
+- **[Performance](docs/PERFORMANCE.md)** - Benchmark baselines and latency targets
+- **[Security Policy](docs/SECURITY.md)** and **[Threat Model](docs/THREAT_MODEL.md)** - Cryptographic design and risk model
+- **[Testing](docs/TESTING.md)** - Test suite structure, coverage map, and how to run tests
+- **[CI Coverage](docs/CI_COVERAGE.md)** - What CI validates and what it does not
+- **[Release Process](docs/RELEASE_PROCESS.md)** - Versioning, release checklist, ship criteria
+- **[Known Issues](docs/KNOWN_ISSUES.md)** - Active and resolved known issues
+- **[Glossary](docs/GLOSSARY.md)** - Canonical terminology reference
 - **[AI Logging Mode](docs/AI_LOGGING_MODE.md)** - Structured logging for AI-assisted development
 
 ---

benchmarks/encode_latency_bench.c

@@ -15,6 +15,7 @@
 #include <stdlib.h>
 #include <string.h>
 #include <time.h>
+#include <limits.h>
 
 /* Raw encoder header is part of the main include */
 #include "../include/rootstream.h"

docs/ARCHITECTURE.md

@@ -8,6 +8,10 @@ Use these documents for neighboring questions:
 - Supported product scope: [`docs/PRODUCT_CORE.md`](PRODUCT_CORE.md)
 - Current execution work: [`docs/microtasks.md`](microtasks.md)
 - Claims evidence: [`docs/audits/claims_audit.md`](audits/claims_audit.md)
+- Architectural boundary rules: [`docs/architecture/BOUNDARY_RULES.md`](architecture/BOUNDARY_RULES.md)
+- Observability and logging: [`docs/OBSERVABILITY.md`](OBSERVABILITY.md)
+- Performance baselines: [`docs/PERFORMANCE.md`](PERFORMANCE.md)
+- Terminology: [`docs/GLOSSARY.md`](GLOSSARY.md)
 
 ## Design Philosophy