Why rqm exists

A requirements document and a test suite drift apart because nothing connects them mechanically. Reviewers ask “is this verified?” and get an answer from memory, from a spreadsheet, or from a green badge in CI that only proves that some tests passed somewhere.

rqm makes the connection explicit and auditable. Requirements are YAML documents in a repository. Tests bind to them through annotations in the source and through selectors written in the requirement. A test run produces evidence. A baseline, written by an explicit promotion step, records what that evidence established. The word “verified” is computed from those facts and can never be written by hand.

Claim, evidence and state

Three kinds of fact are kept apart, and each one lives where it can be reviewed:

  • Claim. A requirement declares which tests are meant to verify it, and sources annotate which requirements they implement. Both live in version control next to the code.
  • Evidence. Test reports record what executed and what happened, for each case and each attempt.
  • State. A declared policy decides whether the evidence is sufficient, applies to the current wording of the requirement, and is complete. The result is computed, and never stored as an opinion.

What rqm covers

  • Writing and validating requirements.
  • Setting up a project (rqm init).
  • Giving every test an identity that tools can agree on.
  • Reading test reports and judging them against a policy.
  • A baseline that records what was verified, and when.
  • Coverage, trace and impact queries.
  • Output that a machine can read and that is the same every time.

What rqm will not do

  • Judge whether a test is good. rqm establishes that a declared body of evidence meets a declared policy. It cannot establish that the evidence proves the requirement, and every output that shows a verification state says so.
  • Compare the meaning of requirement prose. A change of wording changes a hash. rqm does not try to understand it.
  • Synchronise with an issue tracker.
  • Aggregate several repositories.
  • Offer a graphical interface.
  • Report trends over time. The baseline holds the last accepted evidence, not a history.
  • Use the network. rqm reads and writes local files only. Fetching the baseline before a run and storing it afterwards is the job of the CI system, as Running rqm in CI shows.
  • Read the source of languages other than Rust. A test of another runner is bound with a selector in the requirement.

How we know it works

For every outcome of a run, and every sequence of changes to the repository and the policy, rqm has to be able to explain exactly which evidence supports each current claim, and to prove that nothing incomplete, failed, ambiguous, stale or misattributed was promoted. Three small pieces of design answer that:

  • The function that turns facts into a label is total over its inputs, so every combination has a defined label. See Labels and manual evidence.
  • Eligibility is a conjunction of named conditions, each of which can be read in the record of a run. See How a run is judged.
  • Promotion compares a fingerprint of everything the evidence depended on, and refuses on any difference that the evidence depends on. See Promotion: updating the baseline.

The claim is tested end to end. The test file crates/rqm/tests/promote_proof.rs runs real suites through rqm test and rqm baseline update. It shows that no run other than a clean pass creates a record, and that a promotion stopped at any step leaves the baseline as it was.