feat(skills): add spacecraft-clang-guidelines

Introduce a new language-guidelines skill for C (Clang) systems programming. Defines NASA Power of 10 rules (Holzmann's bounds checks, simple flow, small functions, high assertion density), MISRA C safety subsets, CERT C secure coding rules, Clang -fbounds-safety pointer attributes, C11 atomics and threading, and Fil-C compiler setups. Includes zip and skill bundles and README registration.

Co-Authored-By: Antigravity (Gemini 3.5 Flash) <noreply@google.com>

Author: UnbreakableMJ

README.md

@@ -35,6 +35,7 @@ the rules re-attached to every prompt.
 | [`spacecraft-agentic-cli`](spacecraft-agentic-cli/) | Agent-facing UX layer for Spacecraft Software CLIs — pairs with `spacecraft-cli-standard`. |
 | [`spacecraft-brand-guidelines`](spacecraft-brand-guidelines/) | Applies Spacecraft Software's official colors and typography to artifacts. |
 | [`spacecraft-chez-guidelines`](spacecraft-chez-guidelines/) | Functional, safe, concurrent Chez Scheme guidance — R6RS libraries + Akku, pure-first design, `optimize-level` as the safety lever (level 3 = `unsafe`), hand-built mailboxes/channels over real threads (no Fibers), the FFI + AOT/whole-program compilation, and Guile-habit guardrails. |
+| [`spacecraft-clang-guidelines`](spacecraft-clang-guidelines/) | Memory-safe highly-hardened C guidance — NASA Power of 10 Rules (no runtime heap allocation, bounded loops, small functions, high assertion density), MISRA C safety subsets, CERT C secure coding rules, Clang `-fbounds-safety` compiler extensions, and C11 atomics. |
 | [`spacecraft-cli-preference`](spacecraft-cli-preference/) | Modern CLI substitutions: `eza` for `ls`, `rg` for `grep`, `gitway` for Git SSH, etc. |
 | [`spacecraft-cli-standard`](spacecraft-cli-standard/) | Enforces the Spacecraft Software Dual-Mode Self-Documenting CLI Standard (SFRS v1.0.0) on every CLI. |
 | [`spacecraft-cli-shell`](spacecraft-cli-shell/) | Syntax-compliance guard for Nushell / Ion / POSIX / Bash commands. |

spacecraft-clang-guidelines.skill

@@ -0,0 +1,86 @@
+---
+name: spacecraft-clang-guidelines
+description: Use for writing memory-safe highly-hardened C code following Spacecraft Software standards. Triggers on any request involving C programming, GCC, Clang, CMake, Makefiles, C11/C18 standards, CERT C secure coding, MISRA C safety subsets, Gerard J. Holzmann's rules of programming (NASA Power of 10), Clang bounds safety (-fbounds-safety), sanitizers (-fsanitize=address,undefined), Fil-C compiler (fil-c.org), C11 atomics (stdatomic.h), pthreads, or memory allocations (malloc/free avoidance). Trigger even when implicit, e.g. "write a safe C function", "hardening CMake for C compiler bounds check", "implement a bounded loop in C", or "prevent C integer overflow". Do NOT trigger for C++ or Objective-C unless interoperability is explicitly requested. By Mohamed Hammad and Spacecraft Software.
+license: GPL-3.0-or-later
+maintainer: Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>
+website: https://Construct.SpacecraftSoftware.org/
+---
+
+# Spacecraft C (Clang) Guidelines
+
+**Maintainer:** Mohamed Hammad | **Contact:** [Mohamed.Hammad@SpacecraftSoftware.org](mailto:Mohamed.Hammad@SpacecraftSoftware.org)
+**Copyright:** (C) 2026 Mohamed Hammad & Spacecraft Software | **License:** GPL-3.0-or-later
+**Website:** [https://Construct.SpacecraftSoftware.org/](https://Construct.SpacecraftSoftware.org/)
+
+**You are an expert C systems engineer at Spacecraft Software specializing in memory-safe, highly-hardened, and low-latency systems targeting modern compilers and critical standard subsets.** Always follow these rules when writing or reviewing C code. Never deviate. Instructions are explicit, checklist-driven, and self-contained.
+
+## Core Philosophy
+- **Stability and Safety first (Standard §3 Priority 1).** C lacks safety boundaries. Protect projects by using modern bounds-safety features (Clang `-fbounds-safety`), adhering to strict safety-critical subsets (MISRA C, Gerard J. Holzmann's Power of 10 Rules), or utilizing the Fil-C memory-safe compiler.
+- **Then Performance (Priority 2).** Maintain low-latency performance in C systems. Avoid memory management delays at runtime by allocating objects statically or using pre-allocated memory pools instead of dynamically invoking heap allocations.
+- **Explicit Concurrency.** Ensure multi-threaded systems use safe standard threads (C11 `<threads.h>` or POSIX `<pthread.h>`) combined with lock-free atomic updates (C11 `<stdatomic.h>`) to avoid race conditions.
+- **Simple, Bounded Flow.** Simplify logic paths. Ban complex jumping features (`goto`, recursion, long jumps) and ensure every execution loop specifies a constant upper bound.
+
+## Memory Safety & Hardening Mode
+- **Gerard J. Holzmann's Rules (Power of 10):**
+  - **No Dynamic Allocation:** Do not invoke dynamic heap operations (`malloc`, `calloc`, `realloc`, `free`) after system initialization. Pre-allocate arrays or use fixed static memory buffers.
+  - **Simple Flow:** Never use recursion or complex jumps (`setjmp`/`longjmp`). Restrict code to flat structures.
+  - **Small Functions:** Keep function sizes small (under ~60 lines; one printed page) to facilitate verification.
+  - **Assert Preconditions:** Declare at least two assertions (`assert`) per function to check boundaries and variables.
+  - **Small Scope:** Declare variables at the smallest possible scope block.
+- **Clang Bounds Safety (`-fbounds-safety`):** Under supported Clang compilers, compile with `-fbounds-safety`. Use pointer attributes (e.g. `__counted_by(N)`) to configure array bounds. The compiler automatically instruments runtime checks to trap out-of-bounds pointer dereferencing.
+- **Fil-C Drop-in Compiler:** For legacy C modules, compile via the Fil-C compiler toolchain fork of Clang. InvisiCaps capabilities and concurrent garbage collection trap memory faults (use-after-free, double-free) at runtime, aborting safely.
+- **MISRA C & CERT C Rules:** Use explicit types from `<stdint.h>` (e.g. `int32_t`, `uint8_t`) to prevent type size ambiguity. Check all function return values and prevent integer overflow.
+
+## Concurrency vs. Performance Tradeoffs
+- **When Concurrency Helps (Do Atomics / Pools):**
+  - **Lock-free Synchronization:** Using C11 atomics (`_Atomic`, `atomic_store`, `atomic_load`, `atomic_compare_exchange_strong`) to update state registers across threads without lock delays.
+  - **Persistent Thread Pools:** Running background threads using standard C11 `<threads.h>` or POSIX `<pthread.h>` worker loops initialized once at startup.
+- **When Concurrency Hurts (Do NOT Spawn / Race):**
+  - **Dynamic Thread Spawning:** Calling `pthread_create` inside hotspots (e.g., inside frame loops). Thread creation overhead degrades performance; reuse threads.
+  - **Unsynchronized shared variables:** Accessing shared indices across threads without atomic variables or mutexes.
+  - **Lock Deadlocks:** Acquiring multiple locks without a strict order hierarchy.
+
+## Mandatory Abstraction Choice
+Always choose the safety abstraction corresponding to the compiling environment:
+- **Modern Clang compiler:** `-fbounds-safety` compiler flag and bounds annotations.
+- **Legacy code compilation:** Fil-C compiler toolchain.
+- **Testing phase:** AddressSanitizer and UndefinedBehaviorSanitizer flags (`-fsanitize=address,undefined`).
+- **Memory allocation:** Pre-allocated static buffers or memory pools. Banish runtime `malloc`.
+- **Thread management:** Standard C11 `<threads.h>` or POSIX `pthread_t`.
+
+## Required Techniques
+1. **Bounded Loops:** Ensure every loop has a constant upper limit (e.g. `for (int i = 0; i < 100; ++i)`) that static analyzers can verify. Never use unbounded loops.
+2. **Bounds Safety Annotations:** For pointer arguments, use bounds-safety attributes to link pointer and length variables: `void process(int *__counted_by(len) ptr, size_t len)`.
+3. **Hardened CMake Configuration:** Force GCC/Clang warning flags (`-Wall -Wextra -Wpedantic -Werror`) and append sanitizers or bounds safety flags.
+4. **Parameter Validation:** Validate all parameters at the entry of functions. Check pointer arguments against `NULL`.
+5. **Return Code Checking:** Check return values of non-void functions. If a function returns an error code, handle it or bubble it up.
+
+## Build, Tooling & CI (Non-Negotiable)
+- **Toolchain floor:** C11/C18 standards compliant compiler, CMake.
+- **Linter & Static Check:** Enforce coding compliance using `clang-tidy` rules (especially CERT C and MISRA C packages).
+- **Sanitizers Active:** Run test suites with ASan and UBSan flags enabled.
+
+## Anti-Patterns (Never Do These)
+- Invoking `malloc` or `free` inside runtime loops.
+- Writing recursive functions.
+- Leaving loops without constant, statically-verifiable upper limits.
+- Accessing pointers without checking for `NULL`.
+- Using raw type declarations (e.g. `int`, `long`) without explicit `<stdint.h>` sizes.
+- Ignoring or suppressing compile warnings (always use `-Werror`).
+
+## Pre-Commit Checklist (Verify Every Time)
+- [ ] Malloc/free calls are restricted to initialization phases
+- [ ] Every loop has a statically verifiable constant upper bound
+- [ ] No recursive functions are used in the codebase
+- [ ] Function arguments are checked for `NULL` at entry paths
+- [ ] Non-void function return values are captured and validated
+- [ ] Clang `-fbounds-safety` or sanitizers are active in the build config
+- [ ] All variable sizes use explicit types from `<stdint.h>`
+- [ ] Clang-Tidy static checks pass without errors
+- [ ] Compilation completes cleanly under `-Werror` flag
+
+## References & Further Reading
+- Load `references/Spacecraft_Clang_Guidelines.md` for full skeletons (Bounded loop, Clang bounds safety pointer, CMake hardening config, Fil-C commands, and C11 atomics) when deeper patterns are needed.
+- *Further reading* (consulted for background only): JPL Rules for Software Development (Gerard J. Holzmann), MISRA C Rules, CERT C Coding Standard, and LLVM bounds safety manual.
+
+When the user requests C code or review, activate this skill, apply the checklist, and produce code a senior Spacecraft systems engineer would ship.

spacecraft-clang-guidelines.zip

@@ -0,0 +1,228 @@
+# Spacecraft C (Clang) Guidelines — Full Reference
+
+**Version:** 1.0
+**Date:** 2026-07-13
+**Author:** Mohamed Hammad & Spacecraft Software
+**Compatibility:** Clang 18+ (with `-fbounds-safety`), GCC 12+, Fil-C Compiler
+
+This document expands on the `SKILL.md` for C systems programming. It provides complete, compile-checked configurations and skeletons for Holzmann's rules, Clang bounds safety pointer attributes, CMake configurations, and C11 atomics.
+
+---
+
+## 1. Holzmann's Rules: Bounded Loops & Preallocated Arrays
+
+Gerard J. Holzmann's NASA Power of 10 rules ban dynamic memory allocations after initialization and require all loops to have constant upper bounds that can be statically verified.
+
+```c
+#include <stdio.h>
+#include <stdint.h>
+#include <stdbool.h>
+#include <assert.h>
+
+#define MAX_TELEMETRY_SIZE 256
+#define MAX_LOOP_LIMIT 1000
+
+typedef struct {
+    uint32_t sensor_id;
+    float value;
+} TelemetryPacket;
+
+// Static pre-allocated pool (Rule 3: No dynamic allocation after initialization)
+static TelemetryPacket telemetry_pool[MAX_TELEMETRY_SIZE];
+static uint32_t pool_count = 0;
+
+// Function length is short (Rule 4: fits on one page)
+bool register_packet(uint32_t id, float val) {
+    // Assertions verify preconditions (Rule 5: high assertion density)
+    assert(val >= -100.0f);
+    assert(val <= 100.0f);
+
+    if (pool_count >= MAX_TELEMETRY_SIZE) {
+        return false;
+    }
+
+    // Small variable scope (Rule 6)
+    TelemetryPacket *packet = &telemetry_pool[pool_count];
+    packet->sensor_id = id;
+    packet->value = val;
+    pool_count++;
+
+    return true;
+}
+
+float calculate_average(void) {
+    // Rule 7: check parameters/state
+    if (pool_count == 0) {
+        return 0.0f;
+    }
+
+    float sum = 0.0f;
+
+    // Rule 2: Loop must have a statically verifiable upper bound (MAX_TELEMETRY_SIZE)
+    for (uint32_t i = 0; i < MAX_TELEMETRY_SIZE; ++i) {
+        if (i >= pool_count) {
+            break; // loop terminated safely before max bound
+        }
+        sum += telemetry_pool[i].value;
+    }
+
+    return sum / (float)pool_count;
+}
+```
+
+---
+
+## 2. Clang Bounds Safety Pointer Attributes (`-fbounds-safety`)
+
+Clang's `-fbounds-safety` extension enables compile-time and runtime bounds checks for pointers in C. Use annotations like `__counted_by` to link pointer variables to length inputs.
+
+```c
+#include <stdint.h>
+#include <stddef.h>
+#include <assert.h>
+
+// __counted_by(count) ensures ptr dereferences are checked against count
+void process_readings(const float *__counted_by(count) readings, size_t count) {
+    // Validate parameters at entry
+    if (readings == NULL || count == 0) {
+        return;
+    }
+
+    for (size_t i = 0; i < count; ++i) {
+        // Under -fbounds-safety, this index access is automatically bounds-checked.
+        // Attempting to read index i >= count traps out-of-bounds and panics at runtime.
+        float value = readings[i];
+        assert(value >= 0.0f);
+    }
+}
+```
+
+---
+
+## 3. CMakeLists.txt Hardened Configuration
+
+Force warnings-as-errors diagnostics and configure sanitizers and bounds safety compiler flags.
+
+```cmake
+cmake_minimum_required(VERSION 3.20)
+project(SpacecraftC C)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+
+# Enforce strict compiler warnings
+add_compile_options(-Wall -Wextra -Wpedantic -Werror)
+
+# Compiler hardening modes
+if(CMAKE_C_COMPILER_ID STREQUAL "Clang")
+    # Enable Clang bounds safety extension
+    add_compile_options(-fbounds-safety)
+    
+    # Configure AddressSanitizer and UndefinedBehaviorSanitizer for testing builds
+    if(CMAKE_BUILD_TYPE STREQUAL "Debug")
+        add_compile_options(-fsanitize=address,undefined -fno-omit-frame-pointer)
+        add_link_options(-fsanitize=address,undefined)
+    endif()
+elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU")
+    # Enable GCC hardening assertions
+    add_compile_definitions(_GLIBCXX_ASSERTIONS _FORTIFY_SOURCE=3)
+    add_compile_options(-fhardened -fstack-protector-strong)
+endif()
+
+add_executable(telemetry_c_node main.c telemetry.c)
+```
+
+---
+
+## 4. Concurrency: C11 Threads & Atomics
+
+Manage concurrency using standard C11 threads (`<threads.h>`) and atomic operations (`<stdatomic.h>`) to avoid race conditions.
+
+```c
+#include <threads.h>
+#include <stdatomic.h>
+#include <stdbool.h>
+#include <stdio.h>
+
+// Atomic variables prevent data races
+static _Atomic bool running = true;
+static _Atomic uint64_t packet_counter = 0;
+
+int worker_task(void *arg) {
+    (void)arg;
+
+    while (atomic_load(&running)) {
+        // Perform non-blocking I/O or polling...
+        thrd_sleep(&(struct timespec){.tv_sec = 0, .tv_nsec = 50000000}, NULL);
+
+        // Safe atomic increment
+        atomic_fetch_add(&packet_counter, 1);
+    }
+    return 0;
+}
+
+int main(void) {
+    thrd_t thread;
+
+    // Launch worker thread
+    if (thrd_create(&thread, worker_task, NULL) != thrd_success) {
+        return 1;
+    }
+
+    // Run for a short duration
+    thrd_sleep(&(struct timespec){.tv_sec = 1, .tv_nsec = 0}, NULL);
+
+    // Stop worker thread cooperatively
+    atomic_store(&running, false);
+
+    // Join thread to prevent leak
+    int res;
+    thrd_join(thread, &res);
+
+    printf("Processed %lu packets.\n", atomic_load(&packet_counter));
+    return 0;
+}
+```
+
+---
+
+## 5. Legacy C Safety: Fil-C Compiler Setup
+
+Compile legacy C source code with **Fil-C** to enforce dynamic bounds checks and block memory exploits.
+
+### Compilation commands
+```bash
+# Configure Fil-C compiler paths
+export CC=/usr/local/fil-c/bin/clang
+
+# Build C target
+$CC -O2 -std=c11 main.c -o telemetry_c_safe
+
+# Executing the binary panics immediately on memory violations
+./telemetry_c_safe
+```
+
+---
+
+## 6. Common Pitfalls & Troubleshooting
+
+| Pitfall | Symptom | Corrective Action |
+| :--- | :--- | :--- |
+| **Dynamic allocations** | Memory leaks, heap fragmentation | Replace dynamic allocations with static memory pools. |
+| **Pointer arithmetic** | Out-of-bounds memory access | Wrap pointers with Clang `-fbounds-safety` attributes. |
+| **Data races on indices** | Undefined behaviors, race conditions| Lock mutexes or use C11 `<stdatomic.h>` primitives. |
+| **Unbounded loops** | Infinite loops, hang crashes | Enforce constant upper limits on loops. |
+| **Recursion** | Stack overflow crashes | Convert recursive algorithms into iterative loops. |
+
+---
+
+## 7. Code Review Compliance Gate
+
+Before merging C code, verify:
+1. Dynamic heap actions are strictly forbidden after initialization.
+2. Every loop defines a constant upper limit.
+3. No recursive functions or jumping constructs are used.
+4. Function inputs check for `NULL` and return values are verified.
+5. Pointer arguments use `__counted_by` bounds safety attributes under Clang.
+6. C11 `<stdatomic.h>` variable updates are used for thread-safe state variables.
+7. Warnings compile cleanly with warnings-as-errors flag `-Werror`.