Skip to content

Change a frozen item

TL;DR

Start with qmstrace status. Before changing frozen text, obtain an accepted change request that lists the item. Add its fresh ID to Change, make the approved edit, then run qmstrace check --strict. Review the evidence notices as well as the exit code.

  1. Run qmstrace status and identify the governing tag. Resolve any inability to read its historical configuration before editing. See baseline evidence for schema snapshots and complete Git checkouts.

  2. Run qmstrace impact with the existing items' IDs and review the candidate impact list. Ask the project side to reserve any new IDs explicitly. A verified reservation is reported for an unseen start, but cannot supply a graph walk.

  3. Follow the project's acceptance process. Confirm the request file has the configured accepted State and lists every item being changed under Impacts. Do not alter the register merely to silence a finding.

  4. Add the accepted request ID to the item's comma-separated Change field, preserving earlier citations, and make the approved edit. To retire the item, retain its heading and set Status: withdrawn. An old citation already present at the baseline cannot authorize another change.

  5. Run qmstrace check --strict. Address violations and coverage gaps. An unavailable ledger leaves request acceptance unverified even if the command succeeds; arrange verification against the register through the project workflow.

  6. Review downstream suspects and run relevant tests. A successful gate is not evidence that those reviews occurred; edits do not clear the suspect list.

Without a fresh citation, the guard reports:

read: 3 requirements, 2 design elements, 2 components, 4 automated tests
  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: ../ledger/change-requests (1 readable; 0 malformed) — current working tree, not pinned

violations — wrong at any stage; each fails the check:
  V10  docs/req/service-srs.md:12  REQ-SVC-01 is changed since baseline/service/requirements/1, but cites no fresh change request. Fix: restore the item, or stop and ask for an accepted change request listing it; add its ID to Change. An old citation does not authorize another edit.

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.

suspects — review needed; never fail the gate:
  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: 1 violation, 1 gap in 11 items · 7 suspects (informational) · exit 1 · 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

With the accepted request listing the changed item:

read: 3 requirements, 2 design elements, 2 components, 4 automated tests
  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: ../ledger/change-requests (1 readable; 0 malformed) — current working tree, not pinned

gaps — coverage not met yet; only the gate (qmstrace check --strict) fails on them:
  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.

suspects — review needed; never fail the gate:
  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

For finding definitions and exact comparison rules, see Baselines and change control.