States and gates

This page says how three things relate: the status that a person writes, the facts that rqm computes, and the exit code that a command ends with. The rules in full are in How a run is judged, Labels and manual evidence and The command line.

Status is written, verification is computed

A requirement has a status that a person sets: draft, approved, required, deprecated or rejected. The status says where the requirement is in its life, and how much its tests matter. It never says that the requirement is verified, and no status is ever read as, or turned into, a verification state.

Status Meaning The test gate
draft Being written. Not gated. Its run result is shown, never fails the gate and is never recorded.
approved Agreed. If tests exist for it, they must pass. A failing test fails the gate. Missing evidence is reported and does not fail it.
required Agreed, and evidence is mandatory. A failing test fails the gate, and so does missing, incomplete or unreadable evidence.
deprecated Was valid and is being retired. Not gated, and no baseline record is written.
rejected Considered and declined, kept as a decision record. Not gated, and no baseline record is written.

Facts are stored, and the label is computed

One stored value cannot mean both “what the last run saw” and “what the baseline established”. A later failing run would leave verified on the screen. So rqm keeps the facts apart and computes the label from them:

  • the methods of verification the requirement declares,
  • the manual evidence, which is only ever an assertion by its author,
  • the run evaluation: none, satisfied, incomplete, unsatisfied or unknown, for the latest run that saw the requirement as it is now,
  • the baseline evaluation: current, stale, absent, invalid or disabled.

The presentation function turns the last two into one label by ordered rules where the first match wins, and it is total: every combination has a label. It is the only place where a label word is produced, and a test fails if a label is written as a literal anywhere else.

A baseline record is evidence for a content hash. It is not a claim that the requirement is true now. When a newer run on the same hash fails, the record is neither erased nor shown as verified: the label is verification_conflict, and both facts stay visible.

What each command decides

Each command has one predicate for its exit code.

Command It exits 1 when
rqm test a mandatory suite is not clean, or a gated requirement fails its status rule. For approved the run evaluation must not be unsatisfied. For required it must be satisfied. Baseline states never fail the command: pending_baseline and stale are the normal state of a new or edited requirement before promotion.
rqm check never. It validates the whole project without running anything, and it exits 2 on an error. It reports a required requirement that has test in verification and no bound test.
rqm check --baseline a required requirement with test in verification does not present verified, or presents not_applicable without declared manual evidence. It reads no run record, so only the baseline counts. This is the release gate.
rqm coverage --strict any selected coverage class is not empty.

A more severe category takes precedence, as the next section says. rqm test --promote is test followed by baseline update, and its exit code is computed from the final state.

Exit codes

Code Category
0 success
1 a gate failure: the policy says no
2 invalid input: a malformed requirement, report, configuration or baseline, an unusable path or program, a run record that cannot be promoted, or a warning under --strict
3 an operational error: input and output, a timeout, surviving processes, an internal error

When several apply, the order is 2, then 3, then 1, then 0. The exit code gives the category and the diagnostic code gives the cause, so automation branches on the diagnostic code and never on exit 3 alone. Exit 3 keeps one meaning: retrying might help.

Determinism

The commands that only read a project give the same bytes for the same input and the same stored state. They print no timestamp of their own and no absolute path, and nothing in their output depends on the locale or the time zone. Paths are relative to the project root and use / on every platform. rqm test and rqm baseline update carry run ids, times and durations, so they make no such claim, but the order and the structure of their output are fixed.