Baselines and change control¶

TL;DR

status identifies frozen document items; check guards changes to them. A baseline is a configured tag reachable from HEAD. Changing or retiring a frozen item needs a fresh accepted change request listing its ID. Git and request evidence limits remain visible.

Selecting a baseline¶

The configured tag pattern, subject and covers types define a scope. The latest reachable commit governs, by ancestry rather than tag number or date. Overlapping scopes produce one comparison per item. Tags at the same commit are equivalent; their names and annotation metadata are retained. Incomparable governing commits cause exit 2: establish an approved baseline after the merge. A feature branch cannot see a tag outside its ancestry.

Annotated tags supply a tagger and date. Lightweight tags still govern but are labelled weaker evidence. Detached HEAD, linked worktrees and trace roots inside a larger repository work.

schema: the project's, as a verified copy under [schema] — 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
baseline requirements (service): baseline/service/requirements/1 @ f5cb96739aa2
  baseline/service/requirements/1: annotated; tagger Fixture; date 2026-01-01T00:00:00+00:00
controlled document items: 3 frozen · 0 changed · 0 new · 0 removed · 0 withdrawn
baselines: judged from reachable local tags — remote-tag completeness NOT VERIFIED; qmstrace never fetches
baseline baseline/service/requirements/1: historical external/sibling citations NOT VERIFIED — snapshot traversal stops at this repo's edge
change requests: ../ledger/change-requests (0 readable; 0 malformed) — current working tree, not pinned

  REQ-SVC-01 [frozen; baseline/service/requirements/1]  security         origin AGR-1         design elements 1  automated tests 1 (unit 1)         — A call carries a key
  REQ-SVC-02 [frozen; baseline/service/requirements/1]  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 [frozen; baseline/service/requirements/1]  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

Counts concern controlled document items. Changed and removed are subsets of frozen; new items are outside that frozen population. Withdrawn counts current items with that status. Path-derived modules and tests are scanned but the document guard does not require item-level change citations on them; code changes follow the project's commit or pull-request convention.

Historical configuration¶

Each tagged tree supplies its own qmstrace.toml, extraction patterns and schema. A tag from before trace configuration freezes nothing. An existing malformed configuration cannot be treated as pre-trace history. Historical identities survive later pattern and type changes.

The schema must be embedded or stored in the same tagged Git tree. A historical path such as ../ledger/qmstrace.schema.toml cannot be resolved from today's ledger: that would substitute unverified rules for historical evidence. Such a baseline causes exit 2.

For future baselines, give the product repo the project's schema before the tag is cut: run qmstrace ledger copy-schema in the ledger and commit the copy — see share the project's schema. Existing tags are not rewritten automatically. A project adopting this arrangement establishes its next approved baseline under its normal review process; the tool does not retroactively certify older changes.

Offline evidence¶

No command fetches tags or missing objects. Shallow history, unavailable required objects and explicit tag-exclusion settings prevent judgment when baselines are configured. An ordinary full local repository is judged against its reachable local tags. Remote-tag completeness is not verified, even when some local baselines are present. The project's checkout process must obtain the intended history and tags before running the gate.

qmstrace: Baselines cannot be judged in a shallow repository. Fix: obtain full history and tags, then run again; qmstrace never fetches.

Citations and request metadata¶

Change: CR-001, CR-002 is a comma-separated list. A citation is fresh only when absent from the governing snapshot. Adding a citation alone does not change the item's digest. Rewording, changing a link or changing status does; whitespace-only rewrapping does not.

Request files live in the configured directory, with the ID as filename (CR-001.md). Their metadata preamble carries State and Impacts; the accepted value is matched exactly. Impacts is a comma-separated list of authored or path-derived IDs. Fenced examples and fields inside prose sections grant no approval. Duplicate or malformed metadata is a violation.

Situation	Finding
Controlled item changed or added without a fresh citation	V10
Fresh citation names a missing, malformed or unaccepted request	V11
Accepted request does not list the item in `Impacts`	V12
Frozen heading disappears	V13

Every fresh citation offered for a change is checked. A missing request in a readable register fails; an unavailable register permits fresh citations with a NOT VERIFIED notice, retained in quiet output and the result line. Malformed files never receive that permissive fallback. Request files are read from the current working tree, not a verified ledger pin.

baseline requirements (service): baseline/service/requirements/1 @ f5cb96739aa2
  baseline/service/requirements/1: annotated; tagger Fixture; date 2026-01-01T00:00:00+00:00
controlled document items: 3 frozen · 1 changed · 0 new · 0 removed · 0 withdrawn
baselines: judged from reachable local tags — remote-tag completeness NOT VERIFIED; qmstrace never fetches
baseline baseline/service/requirements/1: historical external/sibling citations NOT VERIFIED — snapshot traversal stops at this repo's edge
change requests: NOT VERIFIED — ../ledger/change-requests is unavailable; fresh citations are verified at the ledger's import
G01  docs/req/service-srs.md:29  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.
S01  docs/design/service-design.md:8  DSN-SVC-01 — REQ-SVC-01 (changed) since baseline/service/requirements/1: both versions: baseline distance 1, current distance 1; unchanged — needs review. Review: check this item against the upstream change and test evidence; editing or passing tests does not record review.
S01  tests/unit/test_keys.py:6  tests/unit/test_keys.py::test_a_call_without_a_valid_key_is_refused — REQ-SVC-01 (changed) since baseline/service/requirements/1: both versions: baseline distance 1, current distance 1; unchanged — needs review. Review: check this item against the upstream change and test evidence; editing or passing tests does not record review.
S01  docs/design/service-design.md:13  DSN-SVC-02 — REQ-SVC-01 (changed) since baseline/service/requirements/1: both versions: baseline distance 2, current distance 2; unchanged — needs review. Review: check this item against the upstream change and test evidence; editing or passing tests does not record review.
S01  src/service/keys.py:1  src/service/keys.py — REQ-SVC-01 (changed) since baseline/service/requirements/1: both versions: baseline distance 2, current distance 2; unchanged — needs review. Review: check this item against the upstream change and test evidence; editing or passing tests does not record review.
S01  tests/unit/test_keys.py:12  tests/unit/test_keys.py::TestTheKeyCheck::test_it_runs_before_any_handler — REQ-SVC-01 (changed) since baseline/service/requirements/1: both versions: baseline distance 2, current distance 2; unchanged — needs review. Review: check this item against the upstream change and test evidence; editing or passing tests does not record review.
S01  src/service/store.py:1  src/service/store.py — REQ-SVC-01 (changed) since baseline/service/requirements/1: both versions: baseline distance 3, current distance 3; unchanged — needs review. Review: check this item against the upstream change and test evidence; editing or passing tests does not record review.
S01  tests/integration/test_store.py:5  tests/integration/test_store.py::test_a_record_survives_a_restart — REQ-SVC-01 (changed) since baseline/service/requirements/1: both versions: baseline distance 3, current distance 3; unchanged — needs review. Review: check this item against the upstream change and test evidence; editing or passing tests does not record review.
result: 0 violations, 1 gap in 11 items · 7 suspects (informational) · exit 0 · authoring: gaps do not fail — the gate is qmstrace check --strict · controlled document items: 3 frozen · 1 changed · 0 new · 0 removed · 0 withdrawn · remote-tag completeness NOT VERIFIED · change requests NOT VERIFIED

Withdrawal¶

Retain the heading and write Status: withdrawn, with a fresh accepted citation when frozen. Withdrawal and reactivation are text changes. A withdrawn item raises no coverage gaps of its own, and links with a withdrawn endpoint cannot satisfy active items' coverage rules. Its identity, links, validation findings, traversal and test-result evidence remain visible. Withdrawal does not turn a test result into approval. No special coverage exemption is inferred from another status value.

See Downstream suspects for the review list. A passing change guard establishes neither that downstream work was reviewed nor that an unverified request was accepted.