How to change a baselined requirement

A baselined requirement (one with a stamped REVIEWED_HASH) cannot be silently edited — the post-processor’s --fail-on-suspect gate blocks any PR that drifts a stamped item without a covering change record. This page is the canonical walk-through of the authorised-change process.

End-to-end sequence

Step 1 — Create the change record

A change record is a Markdown file at changes/CR-NNNN.md with YAML frontmatter naming the affected UIDs and the change state.

Example: changing the statement of SRS-007.

---
id: CR-0014
affects:
  - SRS-007
state: approved
approver: doug.youngberg@bioflow.io
approval_date: 2026-04-28
qms_link: https://qms.bioflow.io/changes/CR-0014
---

## Description of change
Update SRS-007 to clarify the impedance threshold language.

## Rationale
Audit feedback from QA review highlighted ambiguity in "high impedance"
without a numeric threshold. Adding the explicit 20 kΩ value.

## Expected downstream impact
ST-014 verifies SRS-007 — the test's STATEMENT may need a wording update
to match, but the assertion itself is unchanged.

Numbering: CR-NNNN is sequential. Pick the next available number; the post-processor doesn’t enforce uniqueness, but conflicts produce confusing audit records, so don’t reuse.

For full state semantics (proposed / approved / implemented / verified) and the parent/child propagation rules, see changes/README.md.

Step 2 — Edit the affected `.sdoc` item

Edit the requirement’s content as needed. Leave REVIEWED_HASH and REVIEWED_BY alone — the auto-stamp Action will overwrite them when this PR merges.

If you also need to update verifying tests (because their ACCEPTANCE_CRITERIA references the changed wording), add those test items to the same change record’s affects: list and edit them in the same PR. The post-processor needs to see them all listed for the change-record coverage to be considered complete.

Step 3 — Open the PR; the gate decides what state the items are in

When the PR pipeline runs, the post-processor classifies each touched item:

Item state	Meaning
`change-in-progress`	The stored `REVIEWED_HASH` doesn’t match current content, but a change record in `state: approved` or `implemented` lists this UID. The `--fail-on-suspect` gate does not fail on this state.
`suspect-native`	Hash mismatch + no change record covering this UID. The gate fails the PR with a clear error.
`suspect-inherited`	This item didn’t change, but a typed-link parent did, and the parent’s change record didn’t list this UID in `affects:`. The gate fails, signalling that the change author should explicitly decide whether the child needs re-review.

If you see the gate fail with suspect-native or suspect-inherited, fix by:

Adding the affected UID to the change record’s affects: list, or
Reverting the unintended drift (if the item shouldn’t have changed)

Then push again; CI re-evaluates.

Step 4 — Code-owner review and merge

Same as the add-requirement workflow Step 5. The qualified reviewer reviews:

The change record’s rationale
The diff of the affected items
The downstream impact assessment

If they approve and the PR pipeline is green, the PR can merge.

Step 5 — Auto-stamp re-baselines the items

Auto-stamp triggers on merge. For each affected .sdoc file:

Re-computes the SHA-256 of the new content
Replaces the old REVIEWED_HASH with the new one
Updates REVIEWED_BY to the current approver

The change record stays in the repo as the historical record of why the change was made and who authorised it. It is not modified by auto-stamp.

Promoting the change record to `verified`

Once the change has been merged and verified (e.g. the related ST passes in CI), the change record’s state: field can be promoted to verified in a follow-up PR. This is administrative — it doesn’t trigger any auto-stamp activity, but it closes the change-record’s lifecycle.

changes/README.md has the full state-transition matrix.

Failure scenarios

Symptom	Likely cause	Fix
`--fail-on-suspect` says `SRS-007 is suspect-native`	You edited SRS-007 without a covering change record, or the change record’s `state:` is still `proposed`	Set state to `approved` (after QMS sign-off) and ensure the UID is in `affects:`
`--fail-on-suspect` says `ST-014 is suspect-inherited`	You changed SRS-007’s content; ST-014 verifies it; the change record didn’t list ST-014	Add ST-014 to the change record’s `affects:` list (declaring you’ve re-reviewed it)
After merge, `REVIEWED_HASH` still matches the old content	Auto-stamp didn’t run, or it ran but its push failed	Re-trigger via Actions → Auto-stamp → Run workflow → enter the PR number
`REVIEWED_BY` lists wrong identity	You and someone else both approved; auto-stamp lists every code-owner approver. If the lister is wrong, that’s a CODEOWNERS misconfiguration — see the CODEOWNERS playbook