A first look¶

TL;DR

In five minutes: get qmstrace, run qmstrace status on the small example project that comes with it, and learn what each block of the output tells you. You need Git and uv.

Get qmstrace¶

The example project lives in qmstrace's repository, so this tutorial runs qmstrace from a clone of it. uv fetches the right Python and everything else on the first run. To use qmstrace in a repo of your own, install a release instead: set up a repo.

git clone https://github.com/Lightbridge-KS/qmstrace.git
cd qmstrace

A private repository

The repository is private. This step needs read access to it.

Meet the example project¶

qmstrace's own tests read a miniature project in tests/fixtures/mini/. It has what a real project has: a ledger repo holding the agreement and the project's rules, and two product repos, service and client, holding requirements, design, code and tests.

In a product repo, every link is written at its downstream end — the test names the requirement it verifies; the requirement names the agreement clause it comes from:

flowchart RL
  req["REQ-SVC-01 · requirement<br/>A call carries a key"] -- Origin --> agr["AGR-1 · agreement clause"]
  dsn["DSN-SVC-01 · design element<br/>Key check"] -- Satisfies --> req
  mod["src/service/keys.py · component"] -- Implements --> dsn
  test["test_a_call_without_a_valid_key_is_refused · automated test"] -- verifies --> req

Each arrow is a line in a file you already write: a field under a requirement's heading, a line under a design section, a sentence in a module's docstring, a marker on a test.

Run it¶

uv run qmstrace -C tests/fixtures/mini/service status

-C runs qmstrace as if it had been started in that folder. Inside a product repo of your own you would leave it out: qmstrace walks up to the nearest qmstrace.toml.

schema: the project's ../ledger/qmstrace.schema.toml, by path — plus this repo's qmstrace.toml
scanned (working tree, not pinned):
  requirement       3 items in  1 file   docs/req/*-srs.md
  design_element    2 items in  1 file   docs/design/*.md
  component         2 items in  2 files  src/**/*.py · 1 file ignored by **/__init__.py
  automated_test    4 items in  2 files  tests/**/test_*.py · test functions: a parametrised function is one automated test
links: 14
external AGR-*: verified against ../ledger/agreement.md (3 declared)
sibling client: 1 requirement — read from ../client's working tree, not pinned; cite its items by ID
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

  REQ-SVC-01  security         origin AGR-1         design elements 1  automated tests 1 (unit 1)         — A call carries a key
  REQ-SVC-02  reliability      origin AGR-2, AGR-3  design elements 1  automated tests 2 (integration 2)  — Records survive a restart

verified by inspection — no recorded basis yet, listed apart:
  REQ-SVC-03  maintainability  origin AGR-3         design elements 0  automated tests 0                  — The record format is written down

categories with no requirement here: functional-suitability, performance-efficiency, compatibility, usability, portability, design-constraint, legal-regulatory
  (a prompt, not a gap — not every product needs one under every category)

suspects: 0 — informational; this repo only

0 violations · 1 gap (G01 ×1) — qmstrace check lists them

Read it, block by block¶

schema: — where the rules come from. Here: the project's trace schema, read by path from the ledger repo beside this one, plus this repo's own qmstrace.toml.
scanned — what was read, per item type. Three requirements in one file, two design elements, two modules — one file was ignored, and the line says by which pattern — and four automated tests, the test functions. A parametrised test function is one automated test, however many times it runs. (A test case is something else: a planned entry in a Test Specification, which this project does not keep — see the chain.) The parenthesis says that the working tree was read, not a pinned commit.
links: — fourteen links entered the graph. A link the rules do not allow never does: it becomes a finding instead.
external AGR-* — every agreement clause a requirement cites was checked against the agreement: it declares three.
sibling client — the project's other product repo, read from beside this one so that its items can be cited by ID. Not pinned: it is whatever is checked out there right now.
baselines: — the project declares two kinds of baseline. This fixture has no matching reachable local tag; the output states that limit and does not claim remote completeness.
One line per requirement — its category, the clause it comes from, and what hangs off it: design elements, and automated tests by level.
verified by inspection — REQ-SVC-03 has no test to show, by design. It is listed apart, because nothing records the inspection yet.
categories with no requirement here — a prompt, not a failure: has each quality been considered?
The last line — nothing is wrong in this repo's trace data, and one coverage rule is not met yet: REQ-SVC-03 has no design element. A gap is work left to do, not an error.

Check it¶

uv run qmstrace -C tests/fixtures/mini/service check

check lists that gap with its next move — what to write, and where. How to work through such a list: Check your work before you commit.

Next¶

Every block, and the pipeline's version of this output: qmstrace status.
What not pinned and not verified here mean, and why they do not fail: Around the repo.

Open the same trace visually¶

From the qmstrace clone, generate a new browser file:

uv run qmstrace -C tests/fixtures/mini/service graph REQ-SVC-01 --out trace.html

Open tests/fixtures/mini/service/trace.html in a browser. The selected requirement is highlighted; its inspector names its origin and source location. Choose depth 1 to limit its immediate neighbors, then use the item list to select a design. Source notices remain below the graph and findings remain in their own list.

The file is generated, so remove it after this exercise. For a real repo, continue with Set up a repo; for detailed browser controls, see Explore a trace.