The baseline file

The baseline is the file where rqm keeps what was verified, and when. It is optional: a project with no baseline key in rqm.yaml has none, and everything that depends on it reads disabled. This page is about reading the baseline. Writing it is a separate step that has its own page.

The baseline is data, not configuration. It is read strictly: a key it does not know, a value outside its enums, a hash that is not 64 lowercase hex digits and a duplicate key are all errors, and there is no best-effort reading of a damaged file.

Layout

schema: 1
hash_algo: "blake3-256/canon-v1"
policy_fingerprint: "<64 hex>"
update:
  run_id: "01KJ9Z6Q3K7M4N8"
  at: "2026-10-23T10:11:12Z"
requirements:
  "<requirement uuid>":
    effective_hash: "<64 hex>"
    result: "satisfied"
    run_id: "01KJ9Z6Q3K7M4N8"
    verified_at: "2026-10-23T10:11:12Z"
    suites: ["unit"]
    cases: 6
    flaky_cases: 0
    provenance: { ... }
    manual_evidence_hash: null
runs:
  "01KJ9Z6Q3K7M4N8": { ... }
  • schema is the version of the layout. Only 1 exists. Any other number is E-BASELINE-SCHEMA-VERSION, and nothing else in the file is looked at.
  • hash_algo names the algorithm and the canonical form the hashes were made with. A baseline made under another algorithm than the one this rqm uses is read, and every record in it is stale with the reason algo_changed.
  • policy_fingerprint is the fingerprint of the evidence policy the baseline was written under.
  • requirements is keyed by the uuid of the requirement, never by its ID, so a renamed requirement keeps its record. Every record names a run in runs, and the file is refused (E-BASELINE-RUN-MISSING) if one does not.
  • result is satisfied. A baseline only ever holds evidence that was good enough to promote, so there is no other value.
  • manual_evidence_hash is null for a requirement that had no manual evidence when the record was written. The key must be present.
  • runs is the history the records point into: when the run started and finished, what it selected, the git state it ran in, and for every suite its exit status, its completeness and its adapter.

Reading

The reader goes in this order, and stops at the first failure:

  1. The bytes are decoded and parsed by the same YAML reader as every other file (see the page on how rqm reads YAML). Duplicate keys, merge keys and tags are refused there.
  2. schema is read alone. A different version is refused before the rest of the file is looked at, so a newer layout gives one clear error and not a list of unknown keys.
  3. The whole file is read into the layout above, with no unknown keys.
  4. The cross-checks run: the keys of requirements are uuids, the keys of runs are run IDs, update.run_id is a run in the file, every record’s run is in runs, and every run has at least one suite.

The fingerprints of the mapping and of the policy subset are checked for their shape only. Whether they are the right ones is decided when the file is written, by rqm baseline update, which is the only writer. See the page on promotion.

What the baseline says about a requirement

For every requirement, the baseline evaluates to one of these. It is computed, never stored.

State Meaning
current A record exists and was made for this text, under this policy and this algorithm.
stale A record exists and something has changed since. The reason is one of algo_changed, policy_changed and content_changed.
absent The baseline has no record for the requirement.
invalid The baseline file cannot be used.
disabled The project has no baseline, or the requirement is a draft.

When several things changed, the reason is the first of the list above in that order: the algorithm, then the policy, then the content of the requirement. The order is fixed so that the same files always give the same reason.

A draft never has a record to be stale against, so it is disabled. An invalid baseline wins over that: a draft in a project whose baseline cannot be read is invalid too, because nothing can be said while the file is unusable.

Missing and broken files

Situation rqm show rqm test
No baseline key disabled disabled
The file is configured and does not exist E-BASELINE-MISSING, exit 2 W-BASELINE-MISSING, goes on as absent
The file cannot be read from disk E-BASELINE-READ, exit 3 the same
The file is not valid an E-BASELINE-* error, exit 2 the same, and no suite is started

rqm test goes on without a file because the run is what produces the evidence for the first one. It refuses to run against a file that exists and is broken, because every label would be computed against nothing.

A record whose uuid belongs to no requirement of the project is not an error. It is reported once per record as I-BASELINE-ORPHAN (information, exit 0), because a deleted or not yet merged requirement is a normal thing for a baseline to remember.

Codes

Code Meaning
E-BASELINE-DUPLICATE-KEY A key appears twice.
E-BASELINE-UNKNOWN-ENUM A value is not one the layout allows.
E-BASELINE-BAD-HASH A hash is not 64 lowercase hex digits.
E-BASELINE-SCHEMA The file does not have the layout: a key is missing, unknown or of the wrong type.
E-BASELINE-SCHEMA-VERSION schema is not 1.
E-BASELINE-RUN-MISSING A record or update names a run that is not in runs.
E-BASELINE-MISSING The configured file does not exist.
E-BASELINE-READ The file could not be read.
I-BASELINE-ORPHAN A record belongs to no requirement of the project.
W-BASELINE-MISSING The configured file does not exist, and the command goes on.

Problems in the YAML itself keep their own E-YAML-* codes. The text and the remedy of every code are in the list of diagnostic codes.