rules_requirements

Requirements-driven development for Bazel projects. Write down what users need, what the product must do, what can go wrong and how each risk is controlled — then let the test suites prove it, and get a traceability report that says, for every item, whether it is verified the way it needs to be.

User needs Requirements Mitigations Risks MIT-1 implemented_by REQ-3 MIT-1 mitigates RISK-1 REQ-1 satisfies UN-1 REQ-2 refines REQ-1 UN-1: What a user must be able to do (no status)UN-1What a user must be able … REQ-1: What the product must do (no status)REQ-1What the product must do REQ-2: A refinement of REQ-1 (no status)REQ-2A refinement of REQ-1 REQ-3: A risk control, as a requirement (no status)REQ-3A risk control, as a requ… MIT-1: Risk control measure (no status)MIT-1Risk control measure RISK-1: Hazard -> harm (no status)RISK-1Hazard -> harm

User needs are satisfied by requirements; requirements may refine other requirements; risks are mitigated by risk control measures, which are implemented by requirements. Each requirement claims the test cases that verify it, and every verdict rolls up from there: a user need is validated when the requirements satisfying it are verified, a risk is mitigated when the requirements implementing its controls are verified.

A test case verifies at most one requirement; a set of test cases may together verify one. The tool is built so that one test case cannot count toward two requirements: ownership is decided in one place, ambiguity quarantines the case, and a published report can be re-checked from its JSON alone (One test case, one requirement).

The vocabulary follows the design-control and risk-management structure of IEC 62304, ISO 14971 and IEC 60601-1 (see Background: the standards), kept generic enough for any product that wants an auditable verification and validation argument.

What you get

  • A model you can review in a diff — YAML files for user needs, requirements, risks, mitigations and test methods, one file or one object per file, validated with stable rule codes (The model).

  • Test hooks that emit standard JUnit XML with traceability properties, for pytest, unittest, googletest, plain-assert C++, Rust and node:test, plus a writer for hand-rolled hardware harnesses (Test hooks).

  • Pluggable evidence ingestion — JUnit is the standard; Rust libtest output and signed inspection records are built in; other formats are a small class away (Evidence and ingestors).

  • One owner per test case — verified_by claims individual cases by selector, two requirements claiming one case is a model error with an example case, a case whose evidence names two ids counts for nobody, and a generated lock pins every requirement’s set of cases (One test case, one requirement).

  • Verification rigor, not just coverage — requirements demand a level (analysis < simulation < sil < hil < hitl, or inspection), evidence provides one, and the report tells under-verified and stale apart from verified (Concepts).

  • Reports in HTML, Markdown and deterministic JSON, with a trace graph and a typed gap queue that routes each gap to an agent or to a human gate (Reports).

  • Source annotations — # @rr(REQ-0001): Implements isolated access to secure data — tie requirements to the code that implements them (Source annotations).

  • Hermetic reports in Bazel — tests run inside a build action, the report is a build output, a golden test pins it (Bazel rules).

  • No runtime dependencies — the toolkit is pure Python standard library; YAML parsing is vendored.

Where to start