@hivehub/rulebook 5.4.1 → 5.5.0

package/templates/languages/C.md

@@ -1,333 +1,333 @@
-<!-- C:START -->
-# C Project Rules
-
-## Agent Automation Commands
-
-**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
-
-```bash
-# Complete quality check sequence:
-clang-format --dry-run --Werror src/**/*.c  # Format check
-make lint                 # Linting (if configured)
-make test                 # All tests (100% pass)
-make                      # Build verification
-
-# Memory safety (recommended):
-valgrind --leak-check=full ./build/test  # Memory leak check
-```
-
-## C Configuration
-
-**CRITICAL**: Use C11 or C17 standard with strict warnings enabled.
-
-- **Standard**: C11 or C17
-- **Compiler**: GCC 11+ or Clang 14+
-- **Build System**: CMake 3.20+ (recommended) or Make
-- **Warnings**: Treat all warnings as errors
-- **Sanitizers**: ASAN, UBSAN for memory safety
-
-### CMakeLists.txt Requirements
-
-```cmake
-cmake_minimum_required(VERSION 3.20)
-project(YourProject C)
-
-set(CMAKE_C_STANDARD 17)
-set(CMAKE_C_STANDARD_REQUIRED ON)
-set(CMAKE_C_EXTENSIONS OFF)
-
-# Compiler warnings
-if(MSVC)
-  add_compile_options(/W4 /WX)
-else()
-  add_compile_options(-Wall -Wextra -Werror -pedantic)
-endif()
-
-# Enable sanitizers in Debug mode
-if(CMAKE_BUILD_TYPE STREQUAL "Debug")
-  add_compile_options(-fsanitize=address,undefined)
-  add_link_options(-fsanitize=address,undefined)
-endif()
-
-# Source files
-add_executable(${PROJECT_NAME} src/main.c src/module.c)
-
-# Include directories
-target_include_directories(${PROJECT_NAME} PUBLIC include)
-
-# Enable testing
-enable_testing()
-add_subdirectory(tests)
-```
-
-## Code Quality Standards
-
-### Mandatory Quality Checks
-
-**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
-
-**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
-
-```bash
-# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
-
-# 1. Format check (matches workflow - use --dry-run, not -i!)
-clang-format --dry-run --Werror src/**/*.c include/**/*.h tests/**/*.c
-
-# 2. Static analysis (matches workflow)
-clang-tidy src/**/*.c -- -std=c17 -Wall -Wextra -Werror
-
-# 3. Build with warnings as errors (matches workflow)
-cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_FLAGS="-Werror -Wall -Wextra -pedantic"
-cmake --build build
-
-# 4. Run all tests (MUST pass 100% - matches workflow)
-ctest --test-dir build --output-on-failure --verbose
-
-# 5. Check with Address Sanitizer (matches workflow)
-cmake -B build-asan -DCMAKE_BUILD_TYPE=Debug \
-  -DCMAKE_C_FLAGS="-fsanitize=address,undefined -g"
-cmake --build build-asan
-ctest --test-dir build-asan --output-on-failure
-
-# 6. Check with Valgrind (matches workflow)
-valgrind --leak-check=full --error-exitcode=1 ./build/YourProject
-
-# 7. Check coverage (matches workflow)
-cmake -B build-cov -DCMAKE_BUILD_TYPE=Coverage \
-  -DCMAKE_C_FLAGS="-fprofile-arcs -ftest-coverage"
-cmake --build build-cov
-ctest --test-dir build-cov
-gcov build-cov/CMakeFiles/YourProject.dir/src/*.gcno
-lcov --capture --directory build-cov --output-file coverage.info
-lcov --list coverage.info
-
-# If ANY fails: ❌ DO NOT COMMIT - Fix first!
-```
-
-**If ANY of these fail, you MUST fix the issues before committing.**
-
-**Why This Matters:**
-- Running different commands locally than in CI causes "works on my machine" failures
-- CI/CD failures happen when local checks differ from workflows
-- Example: Using `clang-format -i` locally but `--dry-run --Werror` in CI = failure
-- Example: Missing `-Werror` flag = warnings pass locally but fail in CI
-- Example: Skipping sanitizers locally = CI catches memory bugs, use-after-free, buffer overflows
-- Example: Not running Valgrind = memory leaks pass locally but fail in CI
-
-### Formatting
-
-- Use clang-format for consistent code style
-- Configuration in `.clang-format`
-- Check formatting in CI (don't auto-format)
-
-Example `.clang-format`:
-```yaml
-Language: C
-BasedOnStyle: LLVM
-IndentWidth: 4
-ColumnLimit: 100
-AllowShortFunctionsOnASingleLine: Empty
-BreakBeforeBraces: Attach
-AlignConsecutiveMacros: true
-```
-
-### Static Analysis
-
-- Use clang-tidy for static analysis
-- Configuration in `.clang-tidy`
-- Enable modernize and bugprone checks
-
-Example `.clang-tidy`:
-```yaml
-Checks: >
-  -*,
-  bugprone-*,
-  clang-analyzer-*,
-  modernize-*,
-  readability-*,
-  performance-*,
-  portability-*
-
-CheckOptions:
-  - key: readability-identifier-naming.FunctionCase
-    value: lower_case
-  - key: readability-identifier-naming.VariableCase
-    value: lower_case
-```
-
-### Testing
-
-- **Framework**: Unity, Check, or CTest
-- **Location**: `/tests` directory
-- **Coverage**: Must meet threshold (80%+)
-- **Sanitizers**: ASAN, UBSAN, Valgrind
-- **Memory Safety**: Zero memory leaks
-
-Example Unity test:
-```c
-#include "unity.h"
-#include "module.h"
-
-void setUp(void) {
-    // Setup before each test
-}
-
-void tearDown(void) {
-    // Cleanup after each test
-}
-
-void test_function_should_return_expected_value(void) {
-    int result = my_function(10);
-    TEST_ASSERT_EQUAL_INT(20, result);
-}
-
-void test_function_should_handle_null_pointer(void) {
-    TEST_ASSERT_NULL(my_function_with_null(NULL));
-}
-
-int main(void) {
-    UNITY_BEGIN();
-    RUN_TEST(test_function_should_return_expected_value);
-    RUN_TEST(test_function_should_handle_null_pointer);
-    return UNITY_END();
-}
-```
-
-## Memory Safety
-
-**CRITICAL**: Always check for memory issues.
-
-### Required Checks
-
-1. **Address Sanitizer (ASAN)**:
-   ```bash
-   gcc -fsanitize=address -g -o program main.c
-   ./program
-   ```
-
-2. **Undefined Behavior Sanitizer (UBSAN)**:
-   ```bash
-   gcc -fsanitize=undefined -g -o program main.c
-   ./program
-   ```
-
-3. **Valgrind**:
-   ```bash
-   valgrind --leak-check=full --show-leak-kinds=all ./program
-   ```
-
-4. **Static Analysis**:
-   ```bash
-   clang-tidy src/**/*.c
-   cppcheck --enable=all --error-exitcode=1 src/
-   ```
-
-### Common Memory Issues to Prevent
-
-```c
-// ❌ BAD: Memory leak
-char *buffer = malloc(100);
-// ... use buffer ...
-// Missing free()
-
-// ✅ GOOD: Proper cleanup
-char *buffer = malloc(100);
-if (buffer == NULL) {
-    return ERROR_NO_MEMORY;
-}
-// ... use buffer ...
-free(buffer);
-buffer = NULL;
-
-// ❌ BAD: Use after free
-char *ptr = malloc(10);
-free(ptr);
-strcpy(ptr, "test");  // UNDEFINED BEHAVIOR!
-
-// ✅ GOOD: NULL after free
-char *ptr = malloc(10);
-free(ptr);
-ptr = NULL;
-if (ptr != NULL) {
-    strcpy(ptr, "test");
-}
-
-// ❌ BAD: Buffer overflow
-char buffer[10];
-strcpy(buffer, "This is too long");  // BUFFER OVERFLOW!
-
-// ✅ GOOD: Bounds checking
-char buffer[10];
-strncpy(buffer, "Safe", sizeof(buffer) - 1);
-buffer[sizeof(buffer) - 1] = '\0';
-```
-
-## Best Practices
-
-### DO's ✅
-
-- **CHECK** return values from all functions
-- **VALIDATE** all pointer arguments for NULL
-- **FREE** all allocated memory
-- **USE** const for immutable pointers
-- **LIMIT** variable scope
-- **ZERO** memory after free for security
-- **BOUNDS** check all array accesses
-- **SANITIZE** all inputs
-
-### DON'Ts ❌
-
-- **NEVER** ignore compiler warnings
-- **NEVER** assume malloc succeeds
-- **NEVER** use gets() (use fgets())
-- **NEVER** use strcpy() (use strncpy() or strlcpy())
-- **NEVER** use sprintf() (use snprintf())
-- **NEVER** dereference NULL pointers
-- **NEVER** return pointers to stack variables
-- **NEVER** skip sanitizer checks
-
-## Security Guidelines
-
-1. **Input Validation**: Validate all external inputs
-2. **Buffer Safety**: Always check bounds
-3. **Integer Overflow**: Check arithmetic operations
-4. **Format String**: Never use user input as format string
-5. **Memory Zeroization**: Zero sensitive data after use
-
-Example secure code:
-```c
-#include <string.h>
-#include <stdlib.h>
-#include <stdio.h>
-
-// Secure string copy with bounds checking
-int safe_strcpy(char *dest, size_t dest_size, const char *src) {
-    if (dest == NULL || src == NULL || dest_size == 0) {
-        return -1;
-    }
-    
-    size_t src_len = strlen(src);
-    if (src_len >= dest_size) {
-        return -1;  // Not enough space
-    }
-    
-    strncpy(dest, src, dest_size - 1);
-    dest[dest_size - 1] = '\0';
-    return 0;
-}
-
-// Secure memory cleanup
-void secure_free(void **ptr, size_t size) {
-    if (ptr == NULL || *ptr == NULL) {
-        return;
-    }
-    
-    // Zero memory before free
-    memset(*ptr, 0, size);
-    free(*ptr);
-    *ptr = NULL;
-}
-```
-
-<!-- C:END -->
+<!-- C:START -->
+# C Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+clang-format --dry-run --Werror src/**/*.c  # Format check
+make lint                 # Linting (if configured)
+make test                 # All tests (100% pass)
+make                      # Build verification
+
+# Memory safety (recommended):
+valgrind --leak-check=full ./build/test  # Memory leak check
+```
+
+## C Configuration
+
+**CRITICAL**: Use C11 or C17 standard with strict warnings enabled.
+
+- **Standard**: C11 or C17
+- **Compiler**: GCC 11+ or Clang 14+
+- **Build System**: CMake 3.20+ (recommended) or Make
+- **Warnings**: Treat all warnings as errors
+- **Sanitizers**: ASAN, UBSAN for memory safety
+
+### CMakeLists.txt Requirements
+
+```cmake
+cmake_minimum_required(VERSION 3.20)
+project(YourProject C)
+
+set(CMAKE_C_STANDARD 17)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_C_EXTENSIONS OFF)
+
+# Compiler warnings
+if(MSVC)
+  add_compile_options(/W4 /WX)
+else()
+  add_compile_options(-Wall -Wextra -Werror -pedantic)
+endif()
+
+# Enable sanitizers in Debug mode
+if(CMAKE_BUILD_TYPE STREQUAL "Debug")
+  add_compile_options(-fsanitize=address,undefined)
+  add_link_options(-fsanitize=address,undefined)
+endif()
+
+# Source files
+add_executable(${PROJECT_NAME} src/main.c src/module.c)
+
+# Include directories
+target_include_directories(${PROJECT_NAME} PUBLIC include)
+
+# Enable testing
+enable_testing()
+add_subdirectory(tests)
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
+
+```bash
+# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
+
+# 1. Format check (matches workflow - use --dry-run, not -i!)
+clang-format --dry-run --Werror src/**/*.c include/**/*.h tests/**/*.c
+
+# 2. Static analysis (matches workflow)
+clang-tidy src/**/*.c -- -std=c17 -Wall -Wextra -Werror
+
+# 3. Build with warnings as errors (matches workflow)
+cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_FLAGS="-Werror -Wall -Wextra -pedantic"
+cmake --build build
+
+# 4. Run all tests (MUST pass 100% - matches workflow)
+ctest --test-dir build --output-on-failure --verbose
+
+# 5. Check with Address Sanitizer (matches workflow)
+cmake -B build-asan -DCMAKE_BUILD_TYPE=Debug \
+  -DCMAKE_C_FLAGS="-fsanitize=address,undefined -g"
+cmake --build build-asan
+ctest --test-dir build-asan --output-on-failure
+
+# 6. Check with Valgrind (matches workflow)
+valgrind --leak-check=full --error-exitcode=1 ./build/YourProject
+
+# 7. Check coverage (matches workflow)
+cmake -B build-cov -DCMAKE_BUILD_TYPE=Coverage \
+  -DCMAKE_C_FLAGS="-fprofile-arcs -ftest-coverage"
+cmake --build build-cov
+ctest --test-dir build-cov
+gcov build-cov/CMakeFiles/YourProject.dir/src/*.gcno
+lcov --capture --directory build-cov --output-file coverage.info
+lcov --list coverage.info
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**If ANY of these fail, you MUST fix the issues before committing.**
+
+**Why This Matters:**
+- Running different commands locally than in CI causes "works on my machine" failures
+- CI/CD failures happen when local checks differ from workflows
+- Example: Using `clang-format -i` locally but `--dry-run --Werror` in CI = failure
+- Example: Missing `-Werror` flag = warnings pass locally but fail in CI
+- Example: Skipping sanitizers locally = CI catches memory bugs, use-after-free, buffer overflows
+- Example: Not running Valgrind = memory leaks pass locally but fail in CI
+
+### Formatting
+
+- Use clang-format for consistent code style
+- Configuration in `.clang-format`
+- Check formatting in CI (don't auto-format)
+
+Example `.clang-format`:
+```yaml
+Language: C
+BasedOnStyle: LLVM
+IndentWidth: 4
+ColumnLimit: 100
+AllowShortFunctionsOnASingleLine: Empty
+BreakBeforeBraces: Attach
+AlignConsecutiveMacros: true
+```
+
+### Static Analysis
+
+- Use clang-tidy for static analysis
+- Configuration in `.clang-tidy`
+- Enable modernize and bugprone checks
+
+Example `.clang-tidy`:
+```yaml
+Checks: >
+  -*,
+  bugprone-*,
+  clang-analyzer-*,
+  modernize-*,
+  readability-*,
+  performance-*,
+  portability-*
+
+CheckOptions:
+  - key: readability-identifier-naming.FunctionCase
+    value: lower_case
+  - key: readability-identifier-naming.VariableCase
+    value: lower_case
+```
+
+### Testing
+
+- **Framework**: Unity, Check, or CTest
+- **Location**: `/tests` directory
+- **Coverage**: Must meet threshold (80%+)
+- **Sanitizers**: ASAN, UBSAN, Valgrind
+- **Memory Safety**: Zero memory leaks
+
+Example Unity test:
+```c
+#include "unity.h"
+#include "module.h"
+
+void setUp(void) {
+    // Setup before each test
+}
+
+void tearDown(void) {
+    // Cleanup after each test
+}
+
+void test_function_should_return_expected_value(void) {
+    int result = my_function(10);
+    TEST_ASSERT_EQUAL_INT(20, result);
+}
+
+void test_function_should_handle_null_pointer(void) {
+    TEST_ASSERT_NULL(my_function_with_null(NULL));
+}
+
+int main(void) {
+    UNITY_BEGIN();
+    RUN_TEST(test_function_should_return_expected_value);
+    RUN_TEST(test_function_should_handle_null_pointer);
+    return UNITY_END();
+}
+```
+
+## Memory Safety
+
+**CRITICAL**: Always check for memory issues.
+
+### Required Checks
+
+1. **Address Sanitizer (ASAN)**:
+   ```bash
+   gcc -fsanitize=address -g -o program main.c
+   ./program
+   ```
+
+2. **Undefined Behavior Sanitizer (UBSAN)**:
+   ```bash
+   gcc -fsanitize=undefined -g -o program main.c
+   ./program
+   ```
+
+3. **Valgrind**:
+   ```bash
+   valgrind --leak-check=full --show-leak-kinds=all ./program
+   ```
+
+4. **Static Analysis**:
+   ```bash
+   clang-tidy src/**/*.c
+   cppcheck --enable=all --error-exitcode=1 src/
+   ```
+
+### Common Memory Issues to Prevent
+
+```c
+// ❌ BAD: Memory leak
+char *buffer = malloc(100);
+// ... use buffer ...
+// Missing free()
+
+// ✅ GOOD: Proper cleanup
+char *buffer = malloc(100);
+if (buffer == NULL) {
+    return ERROR_NO_MEMORY;
+}
+// ... use buffer ...
+free(buffer);
+buffer = NULL;
+
+// ❌ BAD: Use after free
+char *ptr = malloc(10);
+free(ptr);
+strcpy(ptr, "test");  // UNDEFINED BEHAVIOR!
+
+// ✅ GOOD: NULL after free
+char *ptr = malloc(10);
+free(ptr);
+ptr = NULL;
+if (ptr != NULL) {
+    strcpy(ptr, "test");
+}
+
+// ❌ BAD: Buffer overflow
+char buffer[10];
+strcpy(buffer, "This is too long");  // BUFFER OVERFLOW!
+
+// ✅ GOOD: Bounds checking
+char buffer[10];
+strncpy(buffer, "Safe", sizeof(buffer) - 1);
+buffer[sizeof(buffer) - 1] = '\0';
+```
+
+## Best Practices
+
+### DO's ✅
+
+- **CHECK** return values from all functions
+- **VALIDATE** all pointer arguments for NULL
+- **FREE** all allocated memory
+- **USE** const for immutable pointers
+- **LIMIT** variable scope
+- **ZERO** memory after free for security
+- **BOUNDS** check all array accesses
+- **SANITIZE** all inputs
+
+### DON'Ts ❌
+
+- **NEVER** ignore compiler warnings
+- **NEVER** assume malloc succeeds
+- **NEVER** use gets() (use fgets())
+- **NEVER** use strcpy() (use strncpy() or strlcpy())
+- **NEVER** use sprintf() (use snprintf())
+- **NEVER** dereference NULL pointers
+- **NEVER** return pointers to stack variables
+- **NEVER** skip sanitizer checks
+
+## Security Guidelines
+
+1. **Input Validation**: Validate all external inputs
+2. **Buffer Safety**: Always check bounds
+3. **Integer Overflow**: Check arithmetic operations
+4. **Format String**: Never use user input as format string
+5. **Memory Zeroization**: Zero sensitive data after use
+
+Example secure code:
+```c
+#include <string.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+// Secure string copy with bounds checking
+int safe_strcpy(char *dest, size_t dest_size, const char *src) {
+    if (dest == NULL || src == NULL || dest_size == 0) {
+        return -1;
+    }
+    
+    size_t src_len = strlen(src);
+    if (src_len >= dest_size) {
+        return -1;  // Not enough space
+    }
+    
+    strncpy(dest, src, dest_size - 1);
+    dest[dest_size - 1] = '\0';
+    return 0;
+}
+
+// Secure memory cleanup
+void secure_free(void **ptr, size_t size) {
+    if (ptr == NULL || *ptr == NULL) {
+        return;
+    }
+    
+    // Zero memory before free
+    memset(*ptr, 0, size);
+    free(*ptr);
+    *ptr = NULL;
+}
+```
+
+<!-- C:END -->