A Requirement a Statement Cites With No Relationship Is Listed in see_also, With a Reason
Context and Problem Statement
A statement often names another requirement by ID. The #5118 sweep judged each such citation against the SR-13 relationship types. Most got a typed link. Many fit no type: a rationale, a scope boundary, an example, or a link that would close a loop. SR-13-018 forbids a link for those, so the citations stay in the prose with nothing recorded about them.
spec-lint is to fail on a citation with no link, so that a new citation is judged when it is written. That check needs some way to tell a citation already judged as "no relationship" from one nobody has looked at. How does a requirement record that a citation is deliberately not a relationship?
Decision Drivers
- A relationship must assert something true: a change to the target affects the source (SR-13-018, ADR-0160).
- A new citation must be judged when it is written, not found by the next audit.
- A reader of a citation that has no link should be able to tell why.
Considered Options
- A per-requirement
see_alsofield: a list of{spec_id, reason}entries - A new
see_alsorelationship type - Reword every such citation out of its statement
Decision Outcome
Chosen option: "A per-requirement see_also field", because it records the judgment without making the requirements graph claim anything.
Every requirement ID a statement names is then one of two things.
It is the target of a relationship recorded on either end, or it is listed in the citing requirement's see_also with a short reason.
spec-lint fails on a cited ID in neither place.
It also fails on a see_also entry that has gone stale: the ID is no longer cited, is now linked, or names no requirement.
ADR-0160 rejected an exemption marker because each would need a reason, and the markers could grow like the unchecked links did. That cost is accepted here for the citations no type fits, and only for those. A citation that a type fits still gets the link, and the stale-entry check keeps the list from outliving its citations.
Consequences
- Good, because the requirements graph still holds only links whose definitions hold, so the impact walk gets no false answer.
- Good, because a new citation cannot land unjudged: spec-lint asks for a link or a reason.
- Good, because the reason for leaving a citation unlinked is written next to the requirement, where a reader finds it.
- Bad, because a requirement may carry a
see_alsolist as well as its relationships, which is one more field to keep current. - Bad, because an author can put a citation in
see_alsoto quiet the check when a link fits; review must still judge the reason.
Pros and Cons of the Options
A new see_also relationship type
- Good, because the schema keeps one list of cross-references.
- Bad, because a relationship asserts that a change to the target affects the source, and a see-also mention asserts no such thing (SR-13-018).
- Bad, because every graph consumer, from the impact walk to the loop check, would have to skip the type, and one that forgot would give a false answer.
Reword every such citation out of its statement
- Good, because no new field is needed.
- Bad, because the citation is often the clearest way to state a scope boundary or point to where a rule lives, and the reader loses it.
More Information
Generated spec requirements: spec-registry.yaml SR-13-022 (the citation rule), SR-13-023 and SR-13-024 (the spec-lint checks), and SR-02-021 (the see_also field).