qmstrace check¶

TL;DR

qmstrace check lists every violation and every gap in the repo, one line each, with what to do next, followed by every suspect requiring review. Violations always fail it. Gaps — the work not done yet — fail only under --strict, the gate a pull request passes. Run it after every change.

Synopsis¶

Usage: qmstrace check [OPTIONS]

  List every violation, gap and suspect, each with its next move.

  While authoring, gaps do not fail: they are the work not done yet. Under
  --strict — the gate a pull request passes — they do. Violations always fail.
  Suspects never fail, even under --strict: an edit or a passing test does not
  record review.

Options:
  --strict  The gate: gaps fail too; suspects never fail.
  --quiet   Findings only — what could not be verified still shows.
  -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 repo with nothing wrong and nothing left to do:

read: 1 requirement, 1 automated test
  controlled document items: 0 frozen · 0 changed · 0 new · 0 removed · 0 withdrawn
  baselines: judged from reachable local tags — remote-tag completeness NOT VERIFIED; qmstrace never fetches
  baselines: no matching reachable local tag — nothing frozen locally

result: 0 violations, 0 gaps in 2 items · 0 suspects (informational) · exit 0 · authoring: gaps do not fail — the gate is qmstrace check --strict · controlled document items: 0 frozen · 0 changed · 0 new · 0 removed · 0 withdrawn · remote-tag completeness NOT VERIFIED

The same kind of repo under the gate, with one rule not met yet:

read: 3 requirements, 2 design elements, 2 components, 4 automated tests
  controlled document items: 0 frozen · 0 changed · 0 new · 0 removed · 0 withdrawn
  baselines: judged from reachable local tags — remote-tag completeness NOT VERIFIED; qmstrace never fetches
  baselines: no matching reachable local tag — nothing frozen locally
  change requests: NOT VERIFIED — ../ledger/change-requests is unavailable; fresh citations are verified at the ledger's import

gaps — coverage not met yet; only the gate (qmstrace check --strict) fails on them:
  G01  docs/req/service-srs.md:28  REQ-SVC-03: no design element satisfies it yet. Fix: on the design element, write `Satisfies: REQ-SVC-03` under its heading — only if it is true: the link states that the design element satisfies REQ-SVC-03.

result: 0 violations, 1 gap in 11 items · 0 suspects (informational) · exit 1 · gate: gaps fail · controlled document items: 0 frozen · 0 changed · 0 new · 0 removed · 0 withdrawn · remote-tag completeness NOT VERIFIED · change requests NOT VERIFIED

A repo with scanning violations, and the gaps they leave behind:

read: 4 requirements, 2 design elements, 2 components, 6 automated tests
  controlled document items: 0 frozen · 0 changed · 0 new · 0 removed · 0 withdrawn
  baselines: judged from reachable local tags — remote-tag completeness NOT VERIFIED; qmstrace never fetches
  baselines: no matching reachable local tag — nothing frozen locally
  change requests: NOT VERIFIED — ../ledger/change-requests is unavailable; fresh citations are verified at the ledger's import

violations — wrong at any stage; each fails the check:
  V03  docs/design/service-design.md:18  DSN-SVC-02 → Satisfies → REQ-SVC-09: no such item in this repo or its siblings. Fix: declare it in docs/req/*-srs.md, or correct the ID.
  V16  docs/design/service-design.md:24  DSN-SVC-07 is in this heading but not first, so it declares nothing — and nothing else declares it. Fix: to declare it, start a heading with it — `### DSN-SVC-07 — <title>`, a section number before it is fine — where a design element is read (docs/design/*.md); if the heading only names it, correct the ID. Never invent the item to make the ID resolve.
  V07  docs/notes.md:3  REQ-SVC-05 is declared here, but this file is not scanned for a requirement — so the tool cannot see it. Fix: a requirement is read from docs/req/*-srs.md; move it there.
  V05  docs/req/copy-srs.md:1  REQ-SVC-01 has no 'Category:' line. Fix: add '- Category: …' under the heading — one of: functional-suitability, performance-efficiency, compatibility, usability, reliability, maintainability, portability, security, design-constraint, legal-regulatory.
  V05  docs/req/copy-srs.md:1  REQ-SVC-01 has no 'Origin:' line. Fix: add '- Origin: …' under the heading.
  V05  docs/req/copy-srs.md:1  REQ-SVC-01 has no 'Verify-by:' line. Fix: add '- Verify-by: …' under the heading — one of: test, inspection, analysis.
  V01  docs/req/service-srs.md:12  REQ-SVC-01 is declared twice (first at docs/req/copy-srs.md:1). Fix: an ID names exactly one item — give one of them another ID, or, for a module or a test function, another name.
  V02  docs/req/service-srs.md:20  REQ-SVC-7 does not match this repo's ID pattern for a requirement (^REQ-SVC-\d{2}$). Fix: write the ID as [items.requirement] id_pattern says in qmstrace.toml — or, if this heading is prose, do not start it with an ID.
  V09  docs/req/service-srs.md:26  REQ-SVC-02 → Origin → AGR-9: the agreement declares no AGR-9 (it declares AGR-1, AGR-2, AGR-3). Fix: cite a real one, or tell the developer that nothing covers this — never invent one.
  V14  docs/req/service-srs.md:33  REQ-SVC-03 → Origin: 'TBD' is not an ID, so it links nothing. Fix: the 'Origin' line holds IDs only, comma-separated. If nothing real fits, remove the line and tell the developer what is missing — never invent an ID.
  V16  docs/req/service-srs.md:44  REQ-SVC-12 starts a table row, but a table declares nothing — and nothing else declares it. Fix: to declare it, write a heading `### REQ-SVC-12 — <title>` where a requirement is read (docs/req/*-srs.md); if the row only lists it, correct the ID. Never invent the item to make the ID resolve.
  V15  tests/integration/test_store.py:3  a 'verifies' marker set through pytestmark — this tool does not read that form, so it links nothing. Fix: write @pytest.mark.verifies("ID", …) with literal IDs, directly on a test function or on its test class.
  V06  tests/test_top.py:1  tests/test_top.py::test_at_the_top has no test level: its file is not under a level folder. Fix: move the file under tests/<unit | integration | system>/ — a level is information, not a rule, and it is read from where the test sits.
  V08  tests/unit/test_broken.py:1  tests/unit/test_broken.py cannot be parsed: invalid syntax. Fix: correct the file — nothing in it can be traced until it parses.
  V04  tests/unit/test_wrong.py:5  tests/unit/test_wrong.py::test_a_clause → verifies → AGR-1: 'verifies' may point at requirement or design element, not at an origin clause. Fix: point it at the right kind of item, or use the marker that fits — the trace schema's [links] lists them.

gaps — coverage not met yet; only the gate (qmstrace check --strict) fails on them:
  G03  docs/design/service-design.md:17  DSN-SVC-02: no component implements it yet. Fix: the 'Implements:' line at src/service/store.py:5 is outside the module docstring, so it is not read — move it into the docstring.
  G05  docs/design/service-design.md:17  DSN-SVC-02: satisfies no requirement — every design element points back to one. Fix: first fix V03 at docs/design/service-design.md:18 — it refuses the link this rule needs. Do not add a second line.
  G01  docs/req/service-srs.md:22  REQ-SVC-02: no design element satisfies it yet. Fix: on the design element, write `Satisfies: REQ-SVC-02` under its heading — only if it is true: the link states that the design element satisfies REQ-SVC-02.
  G01  docs/req/service-srs.md:29  REQ-SVC-03: no design element satisfies it yet. Fix: the 'Satisfies' table row at docs/design/service-design.md:15 is not read — a table declares nothing; write `Satisfies: …` as a line in the item's section.
  G06  src/service/store.py:1  src/service/store.py: implements no design element — every component points back to one. Fix: the 'Implements:' line at src/service/store.py:5 is outside the module docstring, so it is not read — move it into the docstring.
  G07  tests/test_top.py:1  tests/test_top.py::test_at_the_top: verifies nothing. Fix: write `@pytest.mark.verifies("<requirement or design element ID>")` on the test — only if it is true: the link states that this automated test verifies that requirement or design element.
  G07  tests/unit/test_wrong.py:5  tests/unit/test_wrong.py::test_a_clause: verifies nothing. Fix: first fix V04 at tests/unit/test_wrong.py:5 — it refuses the link this rule needs. Do not add a second line.

result: 15 violations, 7 gaps in 14 items · 0 suspects (informational) · exit 1 · authoring: gaps do not fail — the gate is qmstrace check --strict · controlled document items: 0 frozen · 0 changed · 0 new · 0 removed · 0 withdrawn · remote-tag completeness NOT VERIFIED · change requests NOT VERIFIED

--quiet, in a pipeline where the ledger and the sibling repo are not checked out — what could not be verified still shows, above the findings and again in the result line:

external AGR-*: NOT VERIFIED — ../ledger/agreement.md is not reachable; each cited AGR-N is judged at the ledger's import
sibling service: NOT REACHABLE at ../service
not verified here: 1 citation of another repo's items (REQ-SVC-01) — judged at the ledger's import
controlled document items: 0 frozen · 0 changed · 0 new · 0 removed · 0 withdrawn
baselines: judged from reachable local tags — remote-tag completeness NOT VERIFIED; qmstrace never fetches
baselines: no matching reachable local tag — nothing frozen locally
change requests: NOT VERIFIED — ../ledger/change-requests is unavailable; fresh citations are verified at the ledger's import
G01  docs/req/client-srs.md:3  REQ-CLT-01: no design element satisfies it yet. Fix: this repo declares no design element — declare the type in qmstrace.toml and write it here, or REQ-CLT-01 is met in another repo of the project: qmstrace ledger check, run in the ledger, judges that.
G06  src/client/api.py:1  src/client/api.py: implements no design element — every component points back to one. Fix: this repo declares no design element for it to point at — write the design here and add `Implements: <design element ID>` in its docstring, or cite another repo's only if this item really serves it.
result: 0 violations, 2 gaps in 4 items · 0 suspects (informational) · exit 0 · authoring: gaps do not fail — the gate is qmstrace check --strict · NOT VERIFIED: the agreement, sibling service, 1 cited IDs · controlled document items: 0 frozen · 0 changed · 0 new · 0 removed · 0 withdrawn · remote-tag completeness NOT VERIFIED · change requests NOT VERIFIED

Reading it¶

Part	What it says
`read:`	how many items of each type were read, so an empty result never looks like a clean one
the notices	what this run could not verify or judge — an external source, a sibling, baselines. They show in every form, `--quiet` too
a finding	code · file:line · what is wrong · `Fix:` — the next move, and where a wrong move is tempting, which one not to make
the result line	the counts, the exit code, the mode, and what was not verified. It names the gate, so a reader of the last line alone knows the command a pipeline should run

S01 findings carry a Review: next move and never fail, even under --strict. All suspects appear under --quiet too. See Downstream suspects for complete tested output and historical/current graph evidence.

Violations come first: a gap often exists only because a violation refused the link it needs, and its Fix: then says to fix that violation first — never to add a second line. The codes: Findings. The rules behind the gaps: qmstrace rules. Why gaps do not fail while you work: Kinds of finding.

Exit code¶

The baseline guard adds V10–V13 for unauthorized changes and removals. It can also prevent judgment with exit 2, including ambiguous baseline ancestry or a historical schema outside the tagged tree. See Change a frozen item for tested output.

Mode	`0`	`1`
`qmstrace check`	no violations — gaps may be listed	a violation
`qmstrace check --strict`	no violations and no gaps	a violation or a gap

2 when it cannot judge at all. See Exit codes.