The baseline file
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": { ... }
schemais the version of the layout. Only1exists. Any other number isE-BASELINE-SCHEMA-VERSION, and nothing else in the file is looked at.hash_algonames 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 isstalewith the reasonalgo_changed.policy_fingerprintis the fingerprint of the evidence policy the baseline was written under.requirementsis keyed by the uuid of the requirement, never by its ID, so a renamed requirement keeps its record. Every record names a run inruns, and the file is refused (E-BASELINE-RUN-MISSING) if one does not.resultissatisfied. A baseline only ever holds evidence that was good enough to promote, so there is no other value.manual_evidence_hashisnullfor a requirement that had no manual evidence when the record was written. The key must be present.runsis 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:
- 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.
schemais 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.- The whole file is read into the layout above, with no unknown keys.
- The cross-checks run: the keys of
requirementsare uuids, the keys ofrunsare run IDs,update.run_idis a run in the file, every record’s run is inruns, 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.