docs(notations): decision guide for connecting REQUIREMENT records

CHANGELOG.md

@@ -11,6 +11,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 ### Added
 
 - **`DRIVER.falsifier` and `ASSESSMENT.geographic_scope`** — two optional fields on the motivation-layer primitives (`ELEMENT_PRIMITIVES.md` §7.1, §7.17). `falsifier` is prose recording the observation that would weaken or refute a driver as a standing force; whether it has fired stays a human judgement, not a stored boolean. `geographic_scope` is a list of country codes (ISO 3166-1 alpha-2 or `eu`, reusing the codex jurisdiction vocabulary, `elements/14-codex.md` §1.1) naming where a finding was observed — a region is an explicit list of the countries it comprises, a market is not modelled by this field at all, and the reserved value `[global]` states "everywhere" explicitly, distinct from omitting the field ("not stated"). New `ASSESS-001` (error) validates the value grammar. Purely additive — both fields are optional, no existing field's semantics changed, and an existing `DRIVER` or `ASSESSMENT` file with neither field validates exactly as before. No backfill.
+- **A decision guide for connecting two `REQUIREMENT` records** (`15-requirement.md` §2.4.1) — a compact table distinguishing `parent` (inline, same-TYPE decomposition), `depends_on` (first-class REL, conditional dependency between peer obligations), and `required_for` (first-class REL, obligation-to-release scoping), each with a one-line use/avoid rule. Cross-linked from `17-relations.md` §3, which now also states explicitly that `parent` is an inline alternative to the REL kinds it registers, not a gap in the enum. Documentation only — clarifies existing normative text; no new field, TYPE, or validator rule. (#518)
 
 ### Changed
 

notations/elements/15-requirement.md

@@ -1,8 +1,8 @@
 ---
 title: "Requirement — motivation-layer positive obligation"
-version: "1.2"
+version: "1.3"
 author: "Valerii Korobeinikov"
-last_updated: "2026-08-22"
+last_updated: "2026-08-24"
 status: "draft"
 ---
 
@@ -231,6 +231,18 @@ The same convention applies symmetrically to **CONSTRAINT** ([`ELEMENT_PRIMITIVE
 
 **Precedent — one convention across `parent` fields.** Same-TYPE inline `parent` is the settled v0.x shape across multi-scale primitives: `CHANGE.parent` ([`ELEMENT_PRIMITIVES.md`](../ELEMENT_PRIMITIVES.md) §7.3, capability → process → step decomposition) and `LOCATION.parent` (§7.22, enclosing location). Reusing that shape here keeps the authoring surface uniform; no new pattern is introduced.
 
+### 2.4.1 Decision guide — connecting two `REQUIREMENT` records
+
+Three mechanisms exist for stating how one `REQUIREMENT` relates to another, or to a shipped state of a subject — `parent` above, and two first-class REL kinds registered in [17-relations.md](17-relations.md) §3. They answer different questions; picking the wrong one because two obligations "feel related" is the recurring authoring mistake this guide exists to head off.
+
+| Mechanism | Answers | Shape | Use when | Avoid when |
+|---|---|---|---|---|
+| `parent` (§2.4, above) | Is this obligation a narrower restatement of a broader one? | Inline field, same-TYPE (`REQUIREMENT` → `REQUIREMENT`), timeless | Structural decomposition — a broad obligation split into sub-obligations sharing its source, subject set, or accountability chain | The two obligations are independent, not one narrower than the other (use `depends_on`); or the question is about a release, not another `REQUIREMENT` (use `required_for`) |
+| `depends_on` ([17-relations.md](17-relations.md) §3) | Does obligation A only hold, or only make sense, because obligation B holds? | First-class REL, same-TYPE (`REQUIREMENT` → `REQUIREMENT`), time-aware | A conditional dependency between two peer obligations, neither of which is a restatement of the other | A is actually a narrower form of B (use `parent`); or the link encodes work order — that stays with `ACTION` / `CHANGE` |
+| `required_for` ([17-relations.md](17-relations.md) §3, §3.1) | In which shipped state of the subject must this obligation hold? | First-class REL, cross-TYPE (`REQUIREMENT` → `RELEASE`), time-aware | Scoping one obligation to one release of a `PRODUCT`/`APPLICATION`, so it doesn't read as binding retroactively on every earlier release | The relationship is between two `REQUIREMENT`s, not a release (use `parent` or `depends_on`); or the intent is to record who does the work or by when — that is `ACTION` / `CHANGE`, never a scope statement (§3.1) |
+
+The three never overlap: `parent` and `depends_on` both connect two `REQUIREMENT`s but disagree on whether one is a narrower form of the other; `required_for`'s `to` is always a `RELEASE`, never another `REQUIREMENT`, so it is never a candidate for a REQUIREMENT-to-REQUIREMENT question in the first place.
+
 ### 2.5 `level` — specification tier (ISO/IEC/IEEE 29148 ladder)
 
 `level` records which specification tier the requirement belongs to, per the ISO/IEC/IEEE 29148 StRS → SyRS → SRS ladder:
@@ -312,6 +324,9 @@ The shared lifecycle (`LIFECYCLE-001..004`, [CONTRACT.md](../CONTRACT.md) §7.3)
 
 ## 5. Evolution
 
+**Landed (2026-08-24, connecting-REQUIREMENT decision guide):**
+- §2.4.1 — a compact decision guide distinguishing `parent`, `depends_on`, and `required_for` at one discoverable point, cross-linked from [17-relations.md](17-relations.md) §3. Documentation only: clarifies existing normative text (§2.4's `parent` decomposition, [17-relations.md](17-relations.md) §3's `depends_on` and `required_for` rows), introduces no new field, TYPE, or validator rule.
+
 **Landed (2026-08-22, PRINCIPLE codex TYPE):**
 - `derived_from`'s permitted TYPEs widened to include `PRINCIPLE` (§2 field table, `REQ-003`) — [14-codex.md](14-codex.md) §2.1 adds `PRINCIPLE` as a codex TYPE for a self-held rule with no stated issuing authority or conformance test. Additive: widening a permitted-values enum accepts strictly more than it did before; no existing REQUIREMENT needs updating.
 

notations/elements/17-relations.md

@@ -1,8 +1,8 @@
 ---
 title: "Relations — first-class time-aware links"
-version: "0.2"
+version: "0.3"
 author: "Valerii Korobeinikov"
-last_updated: "2026-08-22"
+last_updated: "2026-08-24"
 status: "draft"
 ---
 
@@ -67,6 +67,8 @@ valid_to: null
 
 The enum is **closed** in v1. Each value names a specific kind of link between two primitive types; the validator enforces both the enum membership and (when the catalogue is loaded) the endpoint TYPE constraints.
 
+**Not every connection is a REL.** Some links are inline fields on the host element instead — timeless, own-record cross-references (§1). `REQUIREMENT.parent` ([15-requirement.md](15-requirement.md) §2.4) is the clearest case: it connects two `REQUIREMENT`s the same way `depends_on` below does, but stays inline because the link carries no time-varying state of its own. [15-requirement.md](15-requirement.md) §2.4.1 is the decision guide for choosing between `parent`, `depends_on`, and `required_for`.
+
 | `type` | Direction (from → to) | Endpoint TYPEs | Semantics |
 |---|---|---|---|
 | `parent` | child → parent | `CAPABILITY` → `CAPABILITY` (V/H sub-grammar applies) | Child capability sits under its parent in the capability hierarchy. Re-parenting a capability — a re-org or a capability split — produces a new relation with its own window. |