Coverage¶
How the must rules are verified. Checked: a tool verifies it in CI today. Planned: the rule names a check that is not built yet. Review: verified in review against the pull-request checklist.
| Area | Must rules | Checked | Planned | Review | Checked share |
|---|---|---|---|---|---|
| Coding agents | 17 | 5 | 10 | 2 | 29% |
| Architecture | 31 | 3 | 18 | 10 | 9% |
| Build and CMake | 21 | 5 | 15 | 1 | 23% |
| C code | 7 | 2 | 3 | 2 | 28% |
| CI and supply chain | 12 | 2 | 10 | 0 | 16% |
| C++ code | 108 | 48 | 41 | 19 | 44% |
| C++20 profile | 40 | 32 | 8 | 0 | 80% |
| Documentation | 35 | 15 | 13 | 7 | 42% |
| Git, review and release | 21 | 6 | 14 | 1 | 28% |
| Hardware and porting | 9 | 0 | 8 | 1 | 0% |
| Repository | 16 | 12 | 4 | 0 | 75% |
| Testing | 21 | 8 | 11 | 2 | 38% |
| All | 338 | 138 | 155 | 45 | 40% |
Checks still to build¶
actionlint: actionlint and zizmor find nothing in the repository's workflowsagents-files: AGENTS.md and CLAUDE.md exist and the handbook sections generated into them are currentallocation-allowlist: a host run with malloc and operator new wrapped records every allocation; any outside start-up or not on the HAL's allowlist failsanomaly-list: the evidence package lists every open bug affecting the release, with impact and workaroundast-rules: a clang-query or libclang script over the compile database for one structural rule; the parameter names it (global-scope, driver-virtual, handler-names, handler-lock-guard, base-nvi, base-tostatus, detail-branch, deadline-compare, isr-calls, bitfield-frames)branch-name: the pull request's head branch matches ^(feat|fix|docs|ci|chore)/[a-z0-9-]+$ or release/<x>.<y>c-naming: clang-tidy readability-identifier-naming with C options (snake_case functions and variables, *_t typedefs, UPPER_CASE enumerators, repository prefix) run on .c files and C API headerschangelog: CHANGELOG.md follows Keep a Changelog; a new version section is the next SemVer step, dated, not emptychangelog-breaking: a pull request labelled breaking adds an entry underchangelog-entry: a pull request that changes files outside docs/ and .github/ changes CHANGELOG.md under [Unreleased], unless it carries the no-changelog labelchangelog-frozen: a pull request's diff of CHANGELOG.md changes only the [Unreleased] section, a new release section and link linesclaude-md-pointer: CLAUDE.md contains exactly the line@AGENTS.mdand nothing elsecmake-configure: a CMake configure test asserts the named property: standard-options, dev-warnings, kb-core-targets, backend-selection, mcu-gates (a wrong-MCU enable must fail), option-defaults, single-togglescodeowners: .github/CODEOWNERS has a*rule naming at least one ownercodeql: a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)compat-table: regenerating the tables derived from catalog/compat.yml leaves the tree unchangedconfig-drift: _config/.clang-format and _config/.clang-tidy equal the handbook's config/ files apart from the headerconformance-tests: every kb::interfaces method has a conformance test, and each mcu/<family> port runs and passes the suitecoverage-justification: every uncovered line, branch or condition is in docs/coverage-justification.yml, and nothing else isctest-timeouts: every test ctest lists has a TIMEOUT propertycubemx-discipline: the .ioc sets ProjectManager.CoupleFile=true and the library-copy option, and regenerating from the .ioc reproduces the committed tree except for USER CODE blocks and the patches listed in PATCHES.mddependabot-config: .github/dependabot.yml updates github-actions weekly with label dependencies and prefix ci, pip where Python tooling exists, and has no gitsubmodule ecosystemdoc-file-names: every file under docs/ is lower-case kebab-case; root README, CHANGELOG, CONTRIBUTING, AGENTS, CLAUDE and LICENSE are exemptdoc-snippets: every C++ block on the documentation site is a snippet from tests/docs/ and those files compile against the current headers (driver-template doc_snippets ctest and the kokeb-docs check)docs-drift: kokeb-docs check finds no generated region (README quickstart, examples list) or figure that differs from what the code generatesdocs-inline-code: no C++ fence longer than one line in docs/ or README.md is written inline; each comes from tests/docs via a --8<-- include or a generated regiondocs-nav: docs/.nav.yml has exactly the five tabs Home, Get started, Concepts, Guides, Reference in order, and contract.md sits under Concepts right after Architecturedocs-page-set: docs/ has every page the documentation standard requires for the repository's declared kind, and each is in the navigationdocs-touched: warns when a pull request changes inc/, a Kconfig or a CMake option without touching README.md, docs/ or CHANGELOG.mddoxyfile-baseline: _config/Doxyfile exists and sets INPUT to the public headers, EXTRACT_ALL and EXTRACT_PRIVATE to NO, WARN_NO_PARAMDOC to YES and the org mainpage, compared with the ci-tools baselinedriver-names: the driver's namespace, class, CMake target, macro prefix and Kconfig prefix all derive from the chip name in the repository name (driver-<chip>)duplicate-code: jscpd finds no block in a board HAL that duplicates kb-hal-common code above the configured thresholderror-enum-values: a compiled test asserts the enumerator values of an error enum against the table on the errors page; the parameter names the enum (driver, kb-status)error-paths-tested: every error value the public API can return is asserted by at least one host testesp-idf-examples: every app in examples/esp32 builds with the pinned ESP-IDF, using the repository root as its component (runs today in driver-template esp32-examples-build-ci.yml through ci-tools ru-build)examples-build: every examples/<platform>/ folder is built by a job of the repository's CIexceptions-rtti-off: the exported library target compiles with -fno-exceptions -fno-rtti, not only the testsexported-target-flags: the library target's own sources and every public header compile with <CHIP>_ENABLE_WARNINGS=ON, the org warning set and -Werrorfile-names: source and test file names match the pattern for the repository's kindfrozen-specs: a pull request changes no specification file whosefrozen:field is setfuzzing: each parser's libFuzzer target runs on the host for a fixed time under ASan and UBSan without a findinghal-lint: the kb-hal-common lints run in a board HAL's or product's CI; the parameter names the lint (boundary, driver-access, allocation, lock)hal-lints: the kb-hal-common boundary, driver-access, allocation and lock lints pass in the board HALhal-startup-test: a HAL host test with the host bind injects a failure into each manager in turn and checks that start-up stops, deinitialises the started managers in reverse and reports the failing ManagerIdheading-skeleton: a Markdown file's headings match a required skeleton in order (parameter: contract, readme, adr, hf-hal-readme, hf-board-spec, hf-protocol-spec)hf-spec-metadata: each HardFOC specification starts with the metadata block (spec type, name, revision, status, covered repos or boards, authored, last reviewed, frozen) and the values validate against a schemahf-spec-names: HardFOC board specification files are named <board>-rev<X.Y[.Z]>.md, one file per revisionhil-evidence: a hardware test record (commit, board and revision, toolchain, tests, results, date) exists for the release and each supported board, in the evidence formathost-tests-matrix: the host tests pass with gcc and clang for each configuration of the named matrix (kb-rtos: KB_RTOS=FREERTOS host shim and KB_RTOS=NONE, with KB_MCU=HOST)include-graph: every #include in library code is allowed by the Layers include table for its folder; the parameter names the layer (driver, utils, rtos, interfaces, mcu, handlers, hal, product) orallinstalled-header-collisions: the install trees of the kb-core packages contain no path twicekb-core-catalog: every drivers/driver-<chip> gitlink is the commit of a v* release tag, has a handlers/<chip>/ folder and a catalog/compat.yml entry, and regenerating compat.yml and the MCU gate table from the pinned driver.yml files changes nothingkb-rtos-matrix: kb-core builds and its host tests pass with KB_RTOS set to FREERTOS (host shim), THREADX and NONEkconfig-symbols: every CONFIG_ symbol the sources read is defined in _config/Kconfig or by ESP-IDFlayer-deps: kb-core's CMake targets link only downward (kb::utils <- kb::rtos <- kb::interfaces <- kb::handlers), read from the CMake file API, and each builds alone with KB_MCU=NONE and KB_MCU=HOSTlighthouse: Lighthouse scores of the built site meet the org budget for accessibility, performance, best practices and SEO (ru-mkdocs-publish runs Lighthouse; register it as implemented once its failing job is confirmed)mcu-foundation-set: each real family under interfaces/mcu/ implements the eight foundation Base* interfaces, and enabling an optional one the family lacks fails at CMake configure timemcu-header-guards: every header under interfaces/mcu/<family>/ starts with an #error guard on KB_MCU_<FAMILY>mcu-matrix: kb-core CI builds every target for each MCU family (STM32 with stub headers), KB_MCU=HOST and NONEmisra-checker: a commercial MISRA C++:2023 / C:2025 checker run, mapped to the compliance matrix (safety level)model-virtual-clock: a chip model for a driver whose port has DelayUs or DelayMs advances a virtual clock in those hooks, and a test runs a delayed-ready mode against itno-attribution: no commit message, pull-request body or review comment carries a Co-Authored-By trailer naming a tool or model, a "Generated with" footer, an AI-disclosure line or a tool banner (runs beside dco)no-heap-link: a test binary that links the library with operator new, malloc and free removed builds and runsopen-safety-issues: the release workflow fails while an open issue labelled safety names the version or its milestoneorg-settings-drift: a scheduledkokeb_org.py --checkfinds no drift between org/ and the repository's live settingspin-bump-isolated: a pull request that moves a gitlink changes nothing else except version_lock.txt, compat.yml and CHANGELOGpin-check: every submodule points at a commit tagged v*.*.* on its own main and matching the manifest or catalog/compat.yml; warns on pull requests to main, fails on release/* and tag pushespin-table-lint: a HardFOC pin table compiles in a host test that rejects names longer than 32 characters or starting with CORE_, COMM_, SYS_ or INTERNAL_port-conformance: the Base* conformance suite passes for the named MCU family, on the host against a mocked SDK and, on a scheduled job with a board, as loopback testspr-body-dod: the pull-request body has the definition-of-done checklist with every item ticked or marked not applicable with a reason, and the hardware line filled (verified, or not verified on hardware with bench steps)pr-template: the pull request body keeps the template's summary, why and verification headings, each non-empty, and every checklist box is ticked or marked not applicablepr-title: the pull request title is at most 72 characters, has no trailing period and no Conventional Commits prefix; a release pull request is titledRelease vX.Y.Zwith the version of the new changelog sectionprose-style: Vale with the Kokeb style; the parameter names the style ruleprovenance-header: the firmware's generated provenance header names its version, release train and the tag and SHA of every submodule, matching .gitmodules and git describeregister-layout-asserts: every register or wire frame struct has static_assert on its size and field offsetsrelease-artifacts: a product release has .bin, .elf, SHA-256 sums and the effective sdkconfig attached, or failsrelease-branch-protection: a ruleset on release/* allows changes only by pull request, squash, linear history and no deletionrelease-evidence: a release carries SHA256SUMS, an SBOM and build provenance; at safety level the evidence package toorelease-notes: the GitHub Release body equals the version's changelog section and has aBench status:linerelease-tag: on a v* tag: the tag matches the declared version, the commit is on main or release/*, its CI gate passed, and a final tag points at the same commit as the latest rc of that versionreproducible-build: two clean builds of the same commit in different directories produce byte-identical artefactsresult-type-traits: static_asserts that the driver's Result<T> is [[nodiscard]], has ok() and an explicit bool conversion, and that T is default-constructible and trivially copyablesafety-label: a pull request touching actuator, power-sequencing, OTP or peripheral-flash paths (labeler config) has the safety label, and a safety-labelled pull request has a human approval before mergesbom: the release attaches an SPDX SBOM listing every component and submodule the build containssdkconfig-defaults: sdkconfig.defaults of every ESP-IDF project sets the named value (freertos-hz is CONFIG_FREERTOS_HZ=1000)secret-scan: gitleaks finds no secret in the pull request's commitssecurity-policy: SECURITY.md exists in .github/ or is inherited from the organisation and names private reportingshared-workflows: every lint, analysis, build, docs and release job calls a kokeb-labs/ci-tools reusable workflow at @v1, and none at @mainsigned-tags: the release tag is a signed annotated tag and the evidence package has a valid signature (safety level)size-budget: flash and RAM use of each built image stays within the budget recorded in the repositoryskill-content-scan: gitleaks finds no secret under .claude/, and no SKILL.md tells an agent to merge, use an admin bypass, --no-verify, a bare NOLINT or skip a checkskill-format: every .claude/skills/<name>/SKILL.md has YAML front matter withnameequal to the kebab-case folder and a one-linedescription, followed by stepsskills-present: .claude/skills has the skills the repository's kind requires: verify in code repositories, bump-pin when .gitmodules is not empty, release when released, add-driver-feature in driversspdx-headers: every source file carries an SPDX licence identifier (REUSE)spelling: typos finds no misspelling (project words in config/typos.toml)stack-usage: the target build with -fstack-usage reports every task entry and ISR within the stack budget in the repository's budget file; unbounded (dynamic) frames failsubmodule-graph: walking .gitmodules across the org's repositories finds no cycle and no submodule that points up the stack (product -> board HAL -> kb-hal-common and kb-core -> drivers)test-naming: host test sources are named test_<unit>.cpp after an existing unit of the librarytest-presence: every unit of the named kind has a test (handler: tests/host/test_<chip>_handler.cpp; public-function: each public function is called by a host test)test-repeat: ctest --repeat until-fail:20 --schedule-random passes, so no test depends on luck or ordertest-report: host test jobs upload a JUnit report and a line and branch coverage report as artifactsthird-party-licences: every third_party/<name>/ has a licence file, and REUSE or scancode finds only MIT-compatible licencestiming-budget: an on-target benchmark job compares measured worst-case times with the stored baseline and fails beyond its margintoolchain-pins: the repository lists exact versions of every supported compiler and ESP-IDF, and every CI build uses exactly those versionstsan: the concurrency host tests pass under ThreadSanitizerunused-error-codes: every chip-specific Error enumerator (16 and up) is returned somewhere in src/ or inc/vendor-regen-diff: CI regenerates vendor code (CubeMX) from the committed project file and fails if the result differs from the committed sources outside user-code markers and PATCHES.mdversion-copies: project(), the package version, the generated version header, Doxyfile PROJECT_NUMBER, driver.yml and the version getter all equal the version in the build settings (driver-template version ctests, less driver.yml)version-lock: each version_lock.txt line REF_<repo>=vX.Y.Z@<sha> matches the submodule's pinned commit and its tagworkflow-permissions: every workflow sets permissions at the top and grants each job the least it needs