qmstrace impact¶

TL;DR

qmstrace impact ID… combines the downstream work affected by several starting items and shows their upstream origins. It prints a candidate Impacts: line for a change request. The analysis stops at this repo's edge. An unseen starting ID rejects the whole request.

Synopsis¶

Usage: qmstrace impact [OPTIONS] {ID…}

  Show the combined downstream items and upstream origins of several starting
  items.

  The Impacts line is a candidate for review, filtered by configured baseline
  types. It stops at this repo's edge. Any unseen starting ID rejects the whole
  request.

Arguments:
  ID…  One or more item IDs visible to this run.  [required]

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.

Supply one or more IDs visible to the run: requirements, design elements, module paths, test node IDs, external clauses or sibling items. Repeated IDs and argument order do not change the output. -C works before or after the command.

Output¶

Two requirements in the miniature service share downstream work. Each downstream item appears once, grouped by its configured type. Origins are those of the starting items, not of every item reached downstream:

impact — working-tree analysis, this repo only

starting items:
  REQ-SVC-01 — A call carries a key · requirement · docs/req/service-srs.md:12
  REQ-SVC-02 — Records survive a restart · requirement · docs/req/service-srs.md:21
  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

downstream — grouped by item type:
  design element (2):
    DSN-SVC-01 — Key check · design element · docs/design/service-design.md:8
    DSN-SVC-02 — Record store · design element · docs/design/service-design.md:13 · also Assumes DSN-SVC-01
  component (2):
    src/service/keys.py · component
    src/service/store.py · component
  automated test (4):
    tests/integration/test_store.py::test_a_record_survives_a_restart · automated test, integration · also verifies DSN-SVC-02
    tests/integration/test_store.py::test_a_restart_loses_no_accepted_record · automated test, integration
    tests/unit/test_keys.py::TestTheKeyCheck::test_it_runs_before_any_handler · automated test, unit
    tests/unit/test_keys.py::test_a_call_without_a_valid_key_is_refused · automated test, unit

upstream origins — of the starting items:
  AGR-1 · origin clause, in the agreement
  AGR-2 · origin clause, in the agreement
  AGR-3 · origin clause, in the agreement

candidate for review — configured baseline types, not a claim of edits or frozen state:
Impacts: DSN-SVC-01, DSN-SVC-02, REQ-SVC-01, REQ-SVC-02

starts: 2 · downstream: 2 design elements, 2 components, 4 automated tests · upstream origins: 3 — this repo only

Assumes carries impact forward through further items. Backward, it does not establish ancestry: an assumed item's origins appear only if an ordinary path also reaches them.

The candidate line contains starting and downstream items whose types are covered by a configured baseline. It is sorted and deduplicated. Upstream origins are context, not added to this line. A starting origin can qualify only if its type is itself covered.

The line proposes items to review; it does not claim they all need edits or are frozen. The shared assessment reads baseline evidence and change requests, but candidate membership still depends on configured types, not frozen state. An accepted request's reservation is reported for an unseen start; it does not establish that item's type or links. When no known item type qualifies, the command explains why it emits no candidate line.

Repository boundary¶

A sibling's item is read from its working tree, not pinned. Only links authored in the current repo are traversed; the sibling's own ancestry and downstream work are not scanned:

impact — working-tree analysis, this repo only

starting items:
  REQ-SVC-01 — A call carries a key · requirement, in sibling service — not pinned · ../service/docs/req/service-srs.md:12
  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
  sibling ancestry and downstream links there are not scanned

downstream — grouped by item type:
  automated test (1):
    tests/unit/test_api.py::test_the_service_refuses_a_call_without_a_key · automated test, unit

upstream origins — of the starting items:
  no upstream origins reached here

candidate for review — configured baseline types, not a claim of edits or frozen state:
Impacts: REQ-SVC-01

starts: 1 · downstream: 1 automated test · upstream origins: 0 — this repo only

In a pipeline a cited sibling ID can remain visible even when its source is unavailable. Its type is unknown and it is omitted from the candidate line, explicitly:

impact — working-tree analysis, this repo only

starting items:
  REQ-SVC-01 · not verified here — judged at the ledger's import
  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
  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

downstream — grouped by item type:
  automated test (1):
    tests/unit/test_api.py::test_the_service_refuses_a_call_without_a_key · automated test, unit

upstream origins — of the starting items:
  no upstream origins reached here

candidate for review — configured baseline types, not a claim of edits or frozen state:
  unknown type, omitted from the candidate: REQ-SVC-01
  no candidate line — no items with a known type covered by a baseline

starts: 1 · downstream: 1 automated test · upstream origins: 0 — this repo only

Unread sources, unverified citations and violations that exclude links remain visible. This is a working-tree analysis within one repo, not a project-wide analysis at pins.

Exit codes¶

0 means the requested walk was produced, including its limitations; gaps and violations do not turn this informational command into a gate. Use check to judge the repo.

2 means usage, configuration or unseen starting IDs prevented the request. If even one starting ID is unseen, the entire request is refused: no partial listing and no Impacts: line. The diagnostic lists every unseen ID, nearby matches and source limitations. An unseen ID is never presumed reserved by a change request.

3 means an internal error. See Exit codes.

For the authoring steps, see Write an impact list.