@deftai/directive-content 0.55.0

package/languages/6502-DASM.md

@@ -0,0 +1,132 @@
+# 6502 + DASM Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+
+## Scope
+- This guide covers:
+  1. Fundamental 6502 assembly best practices (architecture-agnostic)
+  2. DASM-specific authoring and build practices
+
+## Standards
+
+### 1) Fundamental 6502 best practices
+
+#### Correctness and control flow
+- ! Initialize execution state explicitly at startup (stack, flags relevant to your platform, and vectors/entry flow).
+- ! Keep branch-distance limits in mind: relative branches are signed 8-bit offsets (−128..+127 from next PC).
+- ~ Use clear, linear control flow with short local branches and explicit fallthrough comments.
+- ~ Prefer `JMP` for tail calls instead of `JSR` + `RTS` chains when behavior is equivalent.
+- ⊗ Assume all indirect control transfers are interchangeable; account for instruction-specific behavior and timing.
+
+#### Addressing and data layout
+- ! Use zero-page intentionally for hot paths and pointer temporaries.
+- ~ Reserve absolute addressing for stable/global data and code readability.
+- ~ Split pointer tables into low/high byte tables when speed/size wins matter.
+- ! Keep tables and pointer math page-aware to avoid accidental cycle penalties.
+
+#### Flags and arithmetic discipline
+- ! Treat status flags (`N,V,B,D,I,Z,C`) as part of function contract when routines are reused.
+- ~ Document which flags a routine clobbers or preserves.
+- ~ Use `ADC`/`SBC` with explicit carry-state intent (avoid hidden flag dependencies).
+- ≉ Use decimal mode (`D`) unless your target/runtime explicitly requires and supports that behavior in-context.
+
+#### Timing and performance
+- ! Budget cycles in timing-critical sections (raster/audio/bitbanging/IRQ windows).
+- ~ Prefer predictable-cycle constructs when determinism matters (avoid hidden page-crossing penalties).
+- ~ Distinguish optimization goals per routine: speed, size, determinism, or RAM footprint.
+- ≉ Micro-optimize everywhere; optimize measured hotspots first.
+
+#### Reentrancy, stack, and interrupts
+- ! Keep IRQ/NMI-visible shared state minimal and explicit.
+- ~ Prefer reentrant patterns for utility routines used from multiple contexts.
+- ~ Use stack depth conservatively; document worst-case nesting.
+- ⊗ Use scratch RAM assumptions that break under nested interrupts or reused dispatch paths.
+
+### 2) DASM-specific best practices
+
+#### File structure and processor declaration
+- ! Put `PROCESSOR` at the top-level entry file, first logical directive.
+- ! Declare `PROCESSOR` exactly once per assembly.
+- ~ Use one master file that `INCLUDE`s modules in deterministic order.
+- ~ Group code/data by `SEG` with explicit intent (ROM code/data vs uninitialized RAM/BSS-style allocation).
+
+#### Expression and syntax discipline
+- ! Use DASM expression syntax consistently (`[]` for parenthesized expressions).
+- ~ Enable strict syntax checking during CI/release builds (`-S`).
+- ~ Prefer explicitness in expressions/macros over terse clever forms.
+
+#### Labels, locality, and subroutines
+- ! Use `SUBROUTINE` boundaries to scope and safely reuse local labels (dot-prefixed labels).
+- ~ Keep local-label naming simple and repeatable inside each subroutine.
+- ~ Use globally unique labels for externally referenced entry points and shared data.
+
+#### Segments, origins, and binary output
+- ! Choose output format intentionally:
+  - `-f1`: origin header + ascending initialized output
+  - `-f2` (RAS): hunked random-access segments (supports non-ascending/reverse-indexed origin workflows)
+  - `-f3`: raw data only (no header), with format-1 ordering constraints
+- ! Keep initialized segment ordering compatible with selected output format.
+- ~ Use uninitialized segments for RAM maps/size accounting without generating bytes.
+- ~ Make fill behavior explicit when advancing origins / reserving space (avoid accidental default-fill reliance).
+
+#### Includes, assets, and portability
+- ! Use `INCDIR`/`INCLUDE`/`INCBIN` with stable relative project layout.
+- ~ Use `INCBIN` skip-offset intentionally when ingesting assets with headers.
+- ~ Keep platform/path assumptions out of assembly source where possible.
+
+#### Build and diagnostics
+- ! Fail builds on assembler errors; treat warnings as actionable.
+- ~ Use symbol/list outputs (`-s`, `-l`/`-L`) for reproducible debugging and review.
+- ~ Pin pass limits (`-p`/`-P`) in automation to detect pathological unresolved-symbol loops.
+- ? Use `-v` levels >0 in local debugging; keep CI logs concise unless troubleshooting.
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Routine contract header (recommended)
+```asm
+; Name: memcpy_zp_ptr
+; In:   src ptr in zp $00/$01, dst ptr in zp $02/$03, len in X
+; Out:  copied bytes
+; Clobbers: A, X, flags N/Z/C
+; Preserves: Y
+```
+
+### Master-file layout (DASM)
+```asm
+        PROCESSOR 6502
+
+        INCDIR "src"
+        INCLUDE "constants.inc"
+        INCLUDE "zeropage.inc"
+
+        SEG CODE
+        ORG $8000
+Reset:  ; ...
+
+        SEG VECTORS
+        ORG $FFFA
+        .word NmiHandler, Reset, IrqHandler
+```
+
+## Compliance Checklist
+- ! Startup/entry code explicitly defines runtime assumptions.
+- ! Branch-range and page-crossing behavior considered in hot code.
+- ! Routine flag/register clobbers are documented.
+- ! `PROCESSOR` is declared once and first in DASM master source.
+- ! Segment/output format policy is explicit and consistent with linker/loader expectations.
+- ! Strict syntax mode and deterministic build options are used in automation.
+
+## Sources
+- MOS Technology, *MCS6500 Microcomputer Family Programming Manual* (1976): https://bitsavers.org/components/mosTechnology/6500-50A_MCS6500pgmManJan76.pdf
+- DASM README (project + docs pointers): https://raw.githubusercontent.com/dasm-assembler/dasm/master/README
+- DASM user text documentation (`docs/dasm.txt`): https://raw.githubusercontent.com/dasm-assembler/dasm/master/docs/dasm.txt
+- NESdev: 6502 optimization patterns: https://www.nesdev.org/wiki/6502_assembly_optimisations
+- NESdev: cycle-counting guidance: https://www.nesdev.org/wiki/Cycle_counting
+- Obelisk/NESdev timing reference landing (linked from cycle docs): http://www.obelisk.me.uk/6502/
+- Masswerk 6502 instruction-set reference: https://www.masswerk.at/6502/6502_instruction_set.html

package/languages/c.md

@@ -0,0 +1,235 @@
+# C Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
+
+**Stack**: C17/C23, CMake 3.25+, clang/GCC; Testing: Unity/cmocka; Analysis: clang-tidy, cppcheck, AddressSanitizer
+
+## Standards
+
+### Documentation
+- ! Doxygen comments for all public APIs (functions, types, macros)
+- ! File header: purpose, author, date, license
+- ! Document preconditions, postconditions, return values, and error conditions
+- ~ Use `/** */` Doxygen style; `//` for inline comments
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Use Unity (embedded/general) or cmocka (mocking) for unit tests
+- ? Use Check or CUnit as alternatives
+- Files: `test_*.c` or `*_test.c`
+
+### Coverage
+- ! ≥85% coverage
+- ! Count src/\*
+- ! Exclude entry points, generated code, vendor/third-party
+
+### Style
+- ! Use clang-format (project `.clang-format` required)
+- ! Use clang-tidy for static analysis
+- ~ Use cppcheck as supplementary static analysis
+- ! Consistent brace style (K&R or Allman — pick one, enforce via clang-format)
+- ! Column limit: 100 characters
+
+### Naming Conventions
+- ! `snake_case` for functions, variables, and file names
+- ! `UPPER_SNAKE_CASE` for macros and constants
+- ! `snake_case_t` suffix for `typedef` types: `typedef struct pixel pixel_t;`
+- ! Prefix public API symbols with module/library name: `mylib_init()`, `mylib_destroy()`
+- ~ Prefix static (file-scope) functions with `_` or keep unprefixed but `static`
+- ⊗ Pollute global namespace with short, generic names
+
+### Types & Integers
+- ! Use `<stdint.h>` fixed-width types (`uint8_t`, `int32_t`, `size_t`) for portable code
+- ! Use `size_t` for sizes, lengths, and array indices
+- ! Use `bool` from `<stdbool.h>` (not `int` for boolean logic)
+- ! Use `enum` for related constants; ⊗ `#define` chains for enumerable values
+- ~ Use `const` aggressively for read-only data and pointer targets
+- ⊗ Rely on implicit `int` (removed in C99+)
+- ⊗ Assume `char` is signed or unsigned — use `unsigned char` or `uint8_t` for byte data
+
+### Memory Management
+- ! Every `malloc`/`calloc`/`realloc` has a corresponding `free` on all code paths
+- ! Check return value of `malloc`/`calloc`/`realloc` for `NULL`
+- ! Set pointers to `NULL` after `free` to prevent use-after-free
+- ! Use `calloc` over `malloc` + `memset` for zero-initialized allocations
+- ! Prefer stack allocation for small, fixed-size data
+- ⊗ Use `realloc` on `NULL` without checking the return value
+- ⊗ Cast the return value of `malloc` (unnecessary in C, hides missing `#include`)
+- ~ Use a consistent allocation/deallocation pattern (init/destroy, open/close)
+- ~ Use `memset_explicit()` (C23) to clear sensitive data before freeing
+- ? Use arena/pool allocators for performance-critical paths
+
+### Strings & Buffers
+- ! Always bounds-check string operations; ⊗ `strcpy`, `strcat`, `sprintf`, `gets`
+- ! Use `snprintf` over `sprintf`; `strncpy`/`strlcpy` over `strcpy`
+- ! Null-terminate all strings explicitly when building manually
+- ! Pass buffer size alongside buffer pointer in all function signatures
+- ⊗ Use `gets()` — removed in C11
+- ~ Use `strnlen` to safely determine string length on untrusted input
+
+### Error Handling
+- ! Check return values of all standard library and system calls
+- ! Use a consistent error pattern: return codes (0 = success, negative = error) or errno
+- ! Set `errno = 0` before calls that use it; check `errno` only after failure indication
+- ! Document error codes for every public function
+- ~ Use `goto cleanup` pattern for multi-resource cleanup (not deeply nested `if`s)
+- ⊗ Silently ignore return values of I/O, allocation, or system calls
+
+### Preprocessor
+- ! Use include guards (`#ifndef`/`#define`/`#endif`) or `#pragma once` in all headers
+- ! Wrap multi-statement macros in `do { ... } while(0)`
+- ! Parenthesize all macro parameters: `#define MAX(a,b) ((a) > (b) ? (a) : (b))`
+- ~ Prefer `static inline` functions over function-like macros when possible
+- ⊗ Define macros that rely on implicit variable names from the calling context
+- ⊗ Use `#define` to redefine standard library functions or keywords
+
+### Concurrency
+- ! Use `<threads.h>` (C11) or POSIX `<pthread.h>` for threading
+- ! Protect shared data with mutexes; document locking order
+- ! Use `_Atomic` types or `<stdatomic.h>` for lock-free shared variables
+- ⊗ Use `volatile` as a synchronization mechanism (it is not one)
+- ~ Prefer message-passing or work-queue patterns over shared mutable state
+- ~ Use Thread Sanitizer (`-fsanitize=thread`) to detect races in CI
+
+### Undefined Behavior
+- ⊗ Rely on undefined behavior (signed overflow, null deref, out-of-bounds, etc.)
+- ! Enable `-Wall -Wextra -Wpedantic -Werror` in CI builds
+- ! Enable sanitizers in debug/CI: `-fsanitize=address,undefined`
+- ~ Enable `-Wconversion -Wshadow -Wformat=2` for stricter checks
+- ~ Use `_Static_assert` (C11) / `static_assert` (C23) for compile-time invariants
+
+### Safety & Security
+- ! Follow [SEI CERT C Coding Standard](https://wiki.sei.cmu.edu/confluence/display/c) for security-sensitive code
+- ! Validate all external input (user, file, network)
+- ⊗ Hardcode secrets, keys, or credentials in source
+- ⊗ Use `system()` with user-supplied input
+- ~ Use ASLR, stack canaries, and `-fstack-protector-strong` in production builds
+- ? Follow MISRA C for safety-critical/embedded projects
+
+### Telemetry
+- See [telemetry.md](../tools/telemetry.md)
+- ~ Structured logging to stderr/syslog for production
+- ? Sentry Native SDK for crash reporting
+- ? OpenTelemetry C for distributed tracing
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Goto Cleanup
+```c
+int process_file(const char *path) {
+    int result = -1;
+    FILE *fp = NULL;
+    char *buf = NULL;
+    fp = fopen(path, "r");          if (!fp) goto cleanup;
+    buf = malloc(BUF_SIZE);          if (!buf) goto cleanup;
+    if (fread(buf, 1, BUF_SIZE, fp) == 0) goto cleanup;
+    result = do_work(buf);
+cleanup:
+    free(buf);  // free(NULL) is safe
+    if (fp) fclose(fp);
+    return result;
+}
+```
+
+### Opaque Types
+```c
+// mylib.h
+typedef struct mylib_ctx mylib_ctx_t;
+mylib_ctx_t *mylib_create(const char *config);
+int          mylib_process(mylib_ctx_t *ctx, const void *data, size_t len);
+void         mylib_destroy(mylib_ctx_t *ctx);
+// mylib.c
+struct mylib_ctx { int fd; size_t count; char name[64]; };
+```
+
+### Testing (Unity + cmocka)
+```c
+// Unity
+#include "unity.h"
+#include "calculator.h"
+void setUp(void) {} void tearDown(void) {}
+void test_add(void) { TEST_ASSERT_EQUAL_INT(5, calc_add(2, 3)); }
+void test_overflow(void) { TEST_ASSERT_EQUAL_INT(CALC_ERR_OVERFLOW, calc_add(INT_MAX, 1)); }
+int main(void) { UNITY_BEGIN(); RUN_TEST(test_add); RUN_TEST(test_overflow); return UNITY_END(); }
+
+// cmocka (--wrap linker flag for mocking)
+#include <cmocka.h>
+int __wrap_socket_send(int fd, const void *buf, size_t len) {
+    check_expected(fd); check_expected(len); return mock_type(int);
+}
+static void test_send_retries(void **state) {
+    (void)state;
+    expect_value(__wrap_socket_send, fd, 42); expect_value(__wrap_socket_send, len, 10);
+    will_return(__wrap_socket_send, -1);
+    expect_value(__wrap_socket_send, fd, 42); expect_value(__wrap_socket_send, len, 10);
+    will_return(__wrap_socket_send, 10);
+    assert_int_equal(0, network_send_with_retry(42, "0123456789", 10));
+}
+int main(void) {
+    const struct CMUnitTest t[] = { cmocka_unit_test(test_send_retries) };
+    return cmocka_run_group_tests(t, NULL, NULL);
+}
+```
+
+### Macros & Static Assertions
+```c
+#define ARRAY_SIZE(arr) (sizeof(arr) / sizeof((arr)[0]))
+#define LOG_ERROR(fmt, ...) do { fprintf(stderr, "[ERROR] %s:%d: " fmt "\n", __FILE__, __LINE__, ##__VA_ARGS__); } while (0)
+static_assert(sizeof(int) >= 4);  // C23
+_Static_assert(sizeof(uint32_t) == 4, "uint32_t must be 4 bytes");  // C11
+_Static_assert(offsetof(struct packet, checksum) == 12, "checksum at offset 12");
+```
+
+## Build Configuration
+
+**CMake** (3.25+): C17/C23 standard, extensions off, `-Wall -Wextra -Wpedantic -Werror -Wconversion -Wshadow -Wformat=2`; add sanitizers (`-fsanitize=address,undefined`) in Debug; optional `--coverage` flag.
+
+**`.clang-format`**: `BasedOnStyle: LLVM`, `IndentWidth: 4`, `ColumnLimit: 100`, `BreakBeforeBraces: Linux`, `PointerAlignment: Right`, `SortIncludes: CaseInsensitive`
+
+**`.clang-tidy`**: Enable `clang-diagnostic-*`, `clang-analyzer-*`, `cert-*`, `bugprone-*`, `performance-*`, `readability-*`, `misc-*`; `WarningsAsErrors: '*'`
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **Deep nesting**: Use functions or `goto cleanup`
+- ≉ **Tagless typedef struct**: Include struct tag for forward declarations
+- ≉ **Mixing signed/unsigned**: Explicit casts + `-Wconversion`
+- ≉ **Global mutable state**: Pass state via struct pointers
+
+## Hygiene
+
+**Types:**
+- ⊗ Implicit `int` return type or implicit function declarations — illegal in C99+; always declare explicitly
+- ⊗ `void*` casts without an inline comment explaining why a generic pointer is necessary
+- ⊗ `int` used as a boolean — use `bool` (`<stdbool.h>`, C99+) for clarity
+
+**Error handling:**
+- ⊗ Ignoring return values of `malloc`, `fread`, `fwrite`, `fclose`, or any function that signals failure via return value
+- ⊗ Empty error branches — all error paths must log, clean up, or propagate
+- ~ Use `-Wunused-result` and `__attribute__((warn_unused_result))` to enforce checked return values at the compiler level
+
+**Dead code:**
+- ~ Run `cppcheck --enable=unusedFunction,unusedVariable` to detect dead functions and variables
+- ~ `-Wunused-function` and `-Wunused-variable` compiler flags catch file-local dead code
+- ⊗ `#pragma GCC diagnostic ignored "-Wunused-function"` to suppress rather than remove dead code
+
+## Compliance Checklist
+
+- ! Doxygen comments for all public APIs
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! Use clang-format and clang-tidy
+- ! `-Wall -Wextra -Wpedantic -Werror` in CI
+- ! Sanitizers enabled in debug/CI builds
+- ! All allocations checked; all resources freed
+- ! Bounds-checked string/buffer operations; ⊗ `strcpy`/`sprintf`/`gets`
+- ! Follow SEI CERT C for security-sensitive code
+- ⊗ Undefined behavior (signed overflow, null deref, out-of-bounds)
+- ! Run `task check` before commit

package/languages/commands.md

@@ -0,0 +1,23 @@
+# Standard Task Commands
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+All language standards files use the task commands below. Language-specific files list only deviations or additions.
+
+## Default Commands
+
+```bash
+task build              # Build
+task test               # Run all tests (unit, integration)
+task test:coverage      # Run tests with coverage report
+task fmt                # Format
+task lint               # Lint / static analysis
+task quality            # All quality checks
+task check              # Pre-commit (! run: fmt+lint+build+test)
+```
+
+## Naming Conventions
+
+- ! Single-language projects use generic names: `build`, `fmt`, `lint`, `test`
+- ! Multi-language projects use namespaced names: `go:fmt`, `py:lint`, `rs:build`
+- See [taskfile.md](../tools/taskfile.md#naming-conventions) for full details

package/languages/cpp.md

@@ -0,0 +1,132 @@
+# C++ Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [telemetry.md](../tools/telemetry.md)
+
+**Stack**: C++20/23, CMake 3.25+, Catch2/GoogleTest, GSL (Guidelines Support Library); CLI: CLI11; TUI: FTXUI; Async: Asio/libcoro
+
+## Standards
+
+### Documentation
+- ! Doxygen comments for all public APIs (classes, functions, namespaces)
+
+### Testing
+See [testing.md](../coding/testing.md).
+
+- ! Use Catch2 or GoogleTest (+ GoogleMock for mocking)
+- Files: `test_*.cpp` or `*_test.cpp`
+
+### Coverage
+- ! ≥85% coverage
+- ! Count src/\*
+- ! Exclude main, examples, generated code
+
+### Style
+- ! Use clang-format (Google/LLVM/Mozilla style)
+- ! Use clang-tidy for linting
+
+### Types
+- ~ Use strong typing (enums, type aliases)
+- ~ Prefer `std::optional`/`std::variant`/`std::expected` for expected errors
+
+### Telemetry
+- See [telemetry.md](../tools/telemetry.md)
+- ~ Structured logging (spdlog) for production
+- ~ Sentry.io for error tracking
+- ? OpenTelemetry C++ for distributed tracing
+
+### Safety
+- ! Avoid buffer overflows
+- ~ Use GSL (`gsl::span`, `gsl::not_null`, `gsl::owner`)
+- ⊗ Use raw arrays or naked pointers for ownership
+
+### Interfaces
+- ! Design clear, minimal interfaces
+- ~ Use abstract base classes or concepts for polymorphism
+
+## Commands
+
+See [commands.md](./commands.md).
+
+## Patterns
+
+### Testing
+- **Catch2**: `TEST_CASE("desc", "[tag]") { SECTION("case") { REQUIRE(result == expected); } }`
+- **GoogleTest**: `TEST(Suite, Name) { EXPECT_EQ(actual, expected); ASSERT_TRUE(cond); }`
+- **GoogleMock**: `MOCK_METHOD(RetType, MethodName, (Args...), (override));` + `EXPECT_CALL(...)`
+
+### Core Patterns
+- **RAII**: ! Use smart pointers (`std::unique_ptr`, `std::shared_ptr`); ⊗ raw `new`/`delete`
+- **Error Handling**: ~ Use `std::expected<T,E>` for expected errors (file not found, parse failure); ~ exceptions with RAII for bugs/resource exhaustion
+- **Containers**: ! Use `std::vector`, `std::array`, `std::span`; ⊗ C arrays
+- **String Views**: ~ Use `std::string_view` for read-only params
+- **Bounds Safety**: ! Use `.at()` for checked access or range-based loops; ~ use `gsl::span` for array views
+- **Const Correctness**: ! Mark methods `const` when they don't modify state; ~ use `const&` for input params
+- **Namespaces**: ! Organize code in namespaces; ⊗ `using namespace` in headers
+- **Modern Loops**: ~ Use `for (const auto& item : container)` instead of manual indexing
+- **Initialization**: ~ Use brace-init `{}` over `()` to avoid narrowing/most-vexing-parse
+- **Templates**: ~ Use concepts (C++20) to constrain template parameters
+- **Rule of Zero/Five**: ~ Let compiler generate special members OR define all 5
+
+## Build Configuration
+
+**CMake essentials**:
+- ! C++20/23, CMake 3.25+
+- ! Warnings: `-Wall -Wextra -Wpedantic -Werror`
+- ! Coverage: `--coverage` flag when `ENABLE_COVERAGE=ON`
+- ! Dependencies: `find_package(Microsoft.GSL)`, `find_package(Catch2 3)` or `GTest`
+
+**clang-format**: BasedOnStyle: Google/LLVM/Mozilla, ColumnLimit: 100, PointerAlignment: Left
+
+**clang-tidy**: Enable clang-diagnostic, clang-analyzer, cppcoreguidelines, modernize, performance, readability; WarningsAsErrors: "*"
+
+## GSL (Guidelines Support Library)
+
+~ Use GSL for bounds and null safety:
+
+- **gsl::span<T>**: Array view with bounds checking (instead of pointer+size)
+- **gsl::not_null<T*>**: Non-nullable pointer guarantee (no null checks needed)
+- **gsl::owner<T*>**: Ownership annotation (prefer smart pointers)
+
+**Installation**: `find_package(Microsoft.GSL CONFIG REQUIRED)` in CMake
+
+## Interface Design
+
+~ Follow C++ Core Guidelines:
+
+- **I.1**: Make interfaces explicit (clear preconditions/postconditions)
+- **I.2**: Avoid non-const global variables (use const or pass as params)
+- **I.4**: Use strong typing (`enum class Status`, `struct UserId`, not raw ints)
+- **I.11**: Never transfer ownership by raw pointer (use `std::unique_ptr<T>`)
+- **I.13**: Don't pass arrays as single pointers (use `gsl::span<T>`)
+
+**Polymorphism**: ~ Abstract base classes OR concepts (C++20)
+
+## Hygiene
+
+**Types:**
+- ⊗ `void*` where a typed pointer, `std::variant`, or template parameter is feasible
+- ⊗ C-style casts `(T)x` — use `static_cast`, `reinterpret_cast`, or `dynamic_cast` explicitly
+- ~ Mark functions `[[nodiscard]]` when callers must not ignore the return value
+
+**Error handling:**
+- ⊗ Empty `catch(...)` or `catch(std::exception&) {}` that swallow exceptions silently
+- ⊗ Discarding `[[nodiscard]]` return values without explicit `(void)` cast and inline comment
+- ⊗ Using exceptions for control flow in tight loops — use `std::expected` (C++23) or error codes
+
+**Dead code:**
+- ~ Run `cppcheck --enable=unusedFunction` to detect unreferenced functions
+- ~ clang-tidy `misc-unused-*` and `readability-function-cognitive-complexity` checks surface dead helpers
+- ⊗ `// NOLINT` or `#pragma warning(disable:...)` without an inline explanation
+
+## Compliance Checklist
+
+- ! Include Doxygen comments for all public APIs
+- ! See [testing.md](../coding/testing.md) for testing requirements
+- ! Use clang-format and clang-tidy
+- ! Follow C++ Core Guidelines for interfaces, resource management, and safety
+- ~ Use GSL types (`gsl::span`, `gsl::not_null`) for bounds/null safety
+- ! Distinguish expected errors (`std::expected`) from exceptional errors (exceptions)
+- ⊗ Use raw arrays, naked `new`/`delete`, or unchecked array access
+- ! Run `task check` before commit