qmstrace rules¶
TL;DR
qmstrace rules prints what check holds this repo to — the link types, the required
fields, the coverage rules — and says which part is the project's and which the repo's own.
It reads the configuration alone, so it answers anywhere, even where nothing else can be read.
Synopsis¶
Usage: qmstrace rules [OPTIONS]
Print the rules in force: the project's trace schema and this repo's own part.
Read from the configuration alone — nothing is scanned.
Options:
-C PATH Run as if qmstrace had been started in PATH, as with git -C. Before
or after the command.
--help Show this message and exit.
Output¶
A product repo that reads the project's trace schema from the ledger beside it:
rules in force here — the project's trace schema, read from ../ledger/qmstrace.schema.toml, and this repo's qmstrace.toml
From the project's trace schema
link types — a field named after a marker is the link; every link is many-to-many
Origin requirement → origin clause
Satisfies design element → requirement
Implements component → design element
verifies automated test → requirement, design element
Assumes requirement, design element → requirement, design element · counts toward no coverage
required fields
requirement: Category ∈ {functional-suitability, performance-efficiency, compatibility, usability, reliability, maintainability, portability, security, design-constraint, legal-regulatory} · Origin · Verify-by ∈ {test, inspection, analysis}
coverage rules — each unmet rule is a gap
G01 every requirement needs an incoming Satisfies — "no design element satisfies it yet."
G02 every requirement where Verify-by = test needs an incoming verifies — "no test verifies it yet." · not for Verify-by = inspection, analysis
G03 every design element needs an incoming Implements — "no component implements it yet."
G04 every design element needs an incoming verifies — "no test verifies it yet."
G05 every design element needs its own Satisfies — "satisfies no requirement — every design element points back to one."
G06 every component needs its own Implements — "implements no design element — every component points back to one."
G07 every automated test needs its own verifies — "verifies nothing."
external AGR-…: declared in agreement.md, in the ledger — cited here, never declared here
change requests CR-…: in change-requests/, licensing a change when accepted and listing the item in Impacts; each edit needs a fresh citation
baselines — reachable local tags; document changes are guarded
requirements: tags matching ^baseline/(?P<subject>[a-z0-9-]+)/requirements/(?P<n>\d+)$ freeze requirement (the subject named in the tag)
product: tags matching ^v\d+\.\d+\.\d+$ freeze requirement, design element (every subject)
From this repo's qmstrace.toml
subjects: service (key SVC)
declares
requirement markdown ^REQ-SVC-\d{2}$ docs/req/*-srs.md
design element markdown ^DSN-SVC-\d{2}$ docs/design/*.md
component python-module ID: the module's path src/**/*.py · ignores **/__init__.py
automated test pytest ID: the test's node ID tests/**/test_*.py
No rule has a stage: in this version every gap fails the gate (qmstrace check --strict).
Rules are judged on this repo's items; whether an item is covered across the project's repos is judged in the ledger, by qmstrace ledger check.
A repo that carries its own schema, with no ledger:
rules in force here — this repo's own schema, under [schema] in qmstrace.toml
From this repo's own schema
link types — a field named after a marker is the link; every link is many-to-many
Origin requirement → origin clause
verifies automated test → requirement
required fields
requirement: Origin
coverage rules — each unmet rule is a gap
G02 every requirement needs an incoming verifies — "no test verifies it yet."
external BRF-…: declared in docs/brief.md, in this repo — cited here, never declared here
baselines — reachable local tags; document changes are guarded
release: tags matching ^v\d+\.\d+\.\d+$ freeze requirement (every subject)
From this repo's qmstrace.toml
subjects: app (key APP)
declares
requirement markdown ^REQ-APP-\d{2}$ docs/req/*-srs.md
automated test pytest ID: the test's node ID tests/**/test_*.py
No rule has a stage: in this version every gap fails the gate (qmstrace check --strict).
Rules are judged on this repo's items; whether an item is covered across the project's repos is judged in the ledger, by qmstrace ledger check.
A product repo in a pipeline, carrying a verified copy of the project's schema. It declares no design elements, and the rules say what that means for it:
rules in force here — the project's trace schema, as a verified copy under [schema], and this repo's qmstrace.toml
From the project's trace schema
link types — a field named after a marker is the link; every link is many-to-many
Origin requirement → origin clause
Satisfies design element → requirement
Implements component → design element
verifies automated test → requirement, design element
Assumes requirement, design element → requirement, design element · counts toward no coverage
required fields
requirement: Category ∈ {functional-suitability, performance-efficiency, compatibility, usability, reliability, maintainability, portability, security, design-constraint, legal-regulatory} · Origin · Verify-by ∈ {test, inspection, analysis}
coverage rules — each unmet rule is a gap
G01 every requirement needs an incoming Satisfies — "no design element satisfies it yet." · cannot be met with the item types this repo scans
G02 every requirement where Verify-by = test needs an incoming verifies — "no test verifies it yet." · not for Verify-by = inspection, analysis
G03 every design element needs an incoming Implements — "no component implements it yet." · applies to no item here: this repo does not scan that type
G04 every design element needs an incoming verifies — "no test verifies it yet." · applies to no item here: this repo does not scan that type
G05 every design element needs its own Satisfies — "satisfies no requirement — every design element points back to one." · applies to no item here: this repo does not scan that type
G06 every component needs its own Implements — "implements no design element — every component points back to one."
G07 every automated test needs its own verifies — "verifies nothing."
external AGR-…: declared in agreement.md, in the ledger — cited here, never declared here
change requests CR-…: in change-requests/, licensing a change when accepted and listing the item in Impacts; each edit needs a fresh citation
baselines — reachable local tags; document changes are guarded
requirements: tags matching ^baseline/(?P<subject>[a-z0-9-]+)/requirements/(?P<n>\d+)$ freeze requirement (the subject named in the tag)
product: tags matching ^v\d+\.\d+\.\d+$ freeze requirement, design element (every subject)
From this repo's qmstrace.toml
subjects: client (key CLT)
declares
requirement markdown ^REQ-CLT-\d{2}$ docs/req/*-srs.md
component python-module ID: the module's path src/**/*.py
automated test pytest ID: the test's node ID tests/**/test_*.py
knows, does not scan: design element
No rule has a stage: in this version every gap fails the gate (qmstrace check --strict).
Rules are judged on this repo's items; whether an item is covered across the project's repos is judged in the ledger, by qmstrace ledger check.
Reading the coverage rules¶
Each rule is one line: its code, the item type it applies to and any where, the link it needs,
and the words its gap uses. Then, only where it applies:
| Note | What it means |
|---|---|
not for Verify-by = inspection, analysis |
the rule's where leaves these values out — such items fall under no rule of this kind, and qmstrace status lists them apart |
applies to no item here |
this repo does not scan the rule's item type, so nothing here can raise the gap |
cannot be met with the item types this repo scans |
the link comes from a type this repo does not scan — the gap stays until the repo declares that type, or the item is met in another repo — judged in the ledger by qmstrace ledger check |
No rule is hidden in the tool, and no rule is restated anywhere else: this command is where to read them. A rule is changed in the project's trace schema, not here.
Configured baseline scopes and change-request requirements are listed too. rules describes
the policy; status and check assess its evidence. See baselines and change control
for ancestry selection, fresh citations and offline evidence limits.
Exit code¶
0, or 2 when the configuration cannot be read.