colregs 0.3.0 → 0.3.1

package/docs/adr/0015-rule-ids-are-paragraph-keys.md

@@ -0,0 +1,191 @@
+# ADR 0015 — Rule ids are paragraph keys in the `rule:` namespace
+
+Date: 2026-09-16
+Status: accepted — Solace's ruling, 2026-09-16
+
+## Context
+
+Issue #121 asked what an applicability entry should be called, and ruling C
+was read as *names, not citations*. The first draft of this ADR wrote that
+reading out: every id became a coined name in an `entry:` namespace —
+`entry:anchored`, `entry:towing_mastheads_long_tow`, `entry:being_overtaken`.
+It never landed and never shipped. Solace superseded that reading on
+2026-09-16 and this file is the replacement.
+
+What the rename was buying was insulation: `cite` is a data field, revised
+whenever the package reads the Rules better, and `14a` had already become
+`14b` when the reading of *which paragraph deems a head-on* moved. An
+identifier containing a data field gets renamed every time the field is.
+
+What it cost is the vocabulary. An entry is a norm out of the Convention,
+and the people who read these ids — and the consumers that store them
+alongside a `cite` anyway — already have a name for every norm in the
+package: the Rule. `rule:13b` is *Rule 13(b)* in the mariner's mouth. A
+coined name is a second vocabulary beside that one, invented here,
+unguessable from the Rules, and needing a lookup in this file to be read
+back as the paragraph it came from. The insulation is worth one rename in
+a pre-1.0 package; the second vocabulary is permanent. Ruled by Solace,
+2026-09-16.
+
+## Decision
+
+1. **The namespace noun is `rule:`.** It replaces `entry:` everywhere. The
+   overload with the Convention's Rules is the point, not an accident to
+   be designed around.
+2. **An id is `rule:<paragraph-slug>`.** The slug is the cite with its
+   punctuation dropped: rule number, paragraph letter attached, each roman
+   subparagraph joined by `_`. `27(a)(i)` → `27a_i`; `13(b)` → `13b`;
+   `11` → `11`; `23(a)(iii)-(iv)` → `23a_iii_iv`.
+3. **A bare id is the paragraph's principal norm.** Where the text yields
+   a further norm from the same paragraph, it takes a third segment after
+   a colon, named in the text's own words: `rule:24a_i` is 24(a)(i)'s two
+   masthead lights and `rule:24a_i:exceeds_200m` its three, the threshold
+   being the Convention's own, which is when a number may appear in a name.
+4. **Where one sentence fuses a deeming test and a duty, both norms are
+   named.** 15(a) gives `rule:15a:crossing` — the classification, effect
+   `encounter: crossing` — and `rule:15a:keep_out_of_the_way` — the
+   precedence, own give-way. `avoid_crossing_ahead` is reserved for 15(a)'s
+   second duty when the `conduct` shape exists; it is not in use.
+5. **A Convention subparagraph keeps its own cite.** 30(d)'s chapeau is
+   `rule:30d`, citing `30(d)`, importing the 30(a)/(b) anchor lights,
+   modality `shall`; the two all-round red lights are `rule:30d_i`, citing
+   `30(d)(i)`, modality `shall-if-practicable` because the paragraph says
+   "if practicable". `30(d)(i)` joins `rules.json` as a skeleton path with
+   this change. `rule:30d_ii` is reserved for the three balls, and lands
+   when day shapes do.
+6. **A jurisdiction override is named by its difference**, and jurisdiction
+   stays a field: `rule:30a:mooring_buoy` and `rule:30b:mooring_buoy`, both
+   `us/inland`. The name says what 33 CFR 90.5 adds, not who adds it.
+7. **13(b) is one symmetric entry.** The two entries that preceded it were
+   identical but for which subject's `geo:rel_bearing_deg` fell in
+   (112.5, 247.5), and both produced `encounter: overtaking`. `rule:13b`
+   reads the same sector object on either subject under `any_of` — the
+   pattern 13(d) already used over `hist:was_overtaking` — because the
+   encounter type belongs to the pair. One paragraph, one norm, one id.
+8. **Every other entry with a unique cite takes the bare slug of it.**
+9. **`represented_paragraphs` ids take the prefix too** — `2a` becomes
+   `rule:2a` — and keep their own list. They no longer need a schema
+   definition of their own: the id pattern is the same one.
+10. **The schema pattern is**
+    `^rule:[0-9]+[a-z]?(_[ivx]+)*(:[a-z][a-z0-9_]*)?$`.
+    **An id is opaque to a consumer.** It looks like a citation and is not
+    one: a consumer that wants the paragraph reads `cite`, and never splits
+    the id to find it. The resemblance is for the human reading a trace;
+    the `cite` field is the machine-readable link to the Convention, and it
+    is the field that moves when the package's reading of a paragraph moves.
+11. **The identifier-diff mechanism is removed, not left dormant.**
+    `retired_entry_ids`, `data/deprecated-identifiers.json`, its schema, the
+    dormant diff test and the retired-id half of the REQ-MODEL-10 collision
+    test all go. Nothing pre-1.0 is immutable, so there was nothing for the
+    registry to hold and no diff for the test to run; a mechanism that
+    cannot fire is a mechanism nobody maintains. It returns, if at all, with
+    the 1.0.0 tag that REQ-MODEL-10's baseline names. Ruled by Solace,
+    2026-09-16.
+
+## The names
+
+`was` is the `entry:` name from the superseded draft of this ADR, which
+shipped in no release. The citation-derived ids that preceded *it* —
+`24a-m2`, `23a1`, `30d-red` — were never names either and are not carried
+forward.
+
+| was | is | cite |
+|---|---|---|
+| `entry:power_forward_masthead` | `rule:23a_i` | 23(a)(i) |
+| `entry:power_second_masthead` | `rule:23a_ii` | 23(a)(ii) |
+| `entry:power_sidelights_sternlight` | `rule:23a_iii_iv` | 23(a)(iii)-(iv) |
+| `entry:air_cushion_non_displacement` | `rule:23b` | 23(b) |
+| `entry:wig_near_surface` | `rule:23c` | 23(c) |
+| `entry:power_under_12m` | `rule:23d_i` | 23(d)(i) |
+| `entry:power_under_7m_slow` | `rule:23d_ii` | 23(d)(ii) |
+| `entry:towing_mastheads` | `rule:24a_i` | 24(a)(i) |
+| `entry:towing_mastheads_long_tow` | `rule:24a_i:exceeds_200m` | 24(a)(i) |
+| `entry:towing_light` | `rule:24a_ii_iv` | 24(a)(ii)-(iv) |
+| `entry:pushing_composite_unit` | `rule:24b` | 24(b) |
+| `entry:pushing_ahead_or_alongside` | `rule:24c` | 24(c) |
+| `entry:being_towed` | `rule:24e` | 24(e) |
+| `entry:sail_sidelights_sternlight` | `rule:25a` | 25(a) |
+| `entry:sail_combined_lantern` | `rule:25b` | 25(b) |
+| `entry:sail_red_over_green` | `rule:25c` | 25(c) |
+| `entry:sail_under_7m` | `rule:25d_i` | 25(d)(i) |
+| `entry:under_oars` | `rule:25d_ii` | 25(d)(ii) |
+| `entry:trawling_green_over_white` | `rule:26b_i` | 26(b)(i) |
+| `entry:trawling_masthead` | `rule:26b_ii` | 26(b)(ii) |
+| `entry:trawling_making_way` | `rule:26b_iii` | 26(b)(iii) |
+| `entry:fishing_red_over_white` | `rule:26c_i` | 26(c)(i) |
+| `entry:fishing_outlying_gear` | `rule:26c_ii` | 26(c)(ii) |
+| `entry:fishing_making_way` | `rule:26c_iii` | 26(c)(iii) |
+| `entry:nuc_red_over_red` | `rule:27a_i` | 27(a)(i) |
+| `entry:nuc_making_way` | `rule:27a_iii` | 27(a)(iii) |
+| `entry:ram_red_white_red` | `rule:27b_i` | 27(b)(i) |
+| `entry:ram_making_way` | `rule:27b_iii` | 27(b)(iii) |
+| `entry:ram_anchored` | `rule:27b_iv` | 27(b)(iv) |
+| `entry:ram_underwater_obstruction` | `rule:27d` | 27(d) |
+| `entry:diving` | `rule:27e_i` | 27(e)(i) |
+| `entry:mine_clearance` | `rule:27f` | 27(f) |
+| `entry:cbd` | `rule:28` | 28 |
+| `entry:pilot` | `rule:29a` | 29(a) |
+| `entry:anchored` | `rule:30a` | 30(a) |
+| `entry:anchored_under_50m` | `rule:30b` | 30(b) |
+| `entry:anchored_deck_lights` | `rule:30c` | 30(c) |
+| `entry:aground_anchor_lights` | `rule:30d` | 30(d) |
+| `entry:aground_red_over_red` | `rule:30d_i` | 30(d)(i) |
+| `entry:anchored_under_7m_not_near_channel` | `rule:30e` | 30(e) |
+| `entry:any_visibility` | `rule:4` | 4 |
+| `entry:in_sight` | `rule:11` | 11 |
+| `entry:restricted_visibility` | `rule:19a` | 19(a) |
+| `entry:power_gives_way_to_nuc` | `rule:18a_i` | 18(a)(i) |
+| `entry:power_gives_way_to_ram` | `rule:18a_ii` | 18(a)(ii) |
+| `entry:power_gives_way_to_fishing` | `rule:18a_iii` | 18(a)(iii) |
+| `entry:power_gives_way_to_sail` | `rule:18a_iv` | 18(a)(iv) |
+| `entry:sail_gives_way_to_nuc` | `rule:18b_i` | 18(b)(i) |
+| `entry:sail_gives_way_to_ram` | `rule:18b_ii` | 18(b)(ii) |
+| `entry:sail_gives_way_to_fishing` | `rule:18b_iii` | 18(b)(iii) |
+| `entry:fishing_gives_way_to_nuc` | `rule:18c_i` | 18(c)(i) |
+| `entry:fishing_gives_way_to_ram` | `rule:18c_ii` | 18(c)(ii) |
+| `entry:avoid_impeding_cbd` | `rule:18d_i` | 18(d)(i) |
+| `entry:wig_keeps_well_clear` | `rule:18f_i` | 18(f)(i) |
+| `entry:not_impeded_remains_obliged` | `rule:8f_iii` | 8(f)(iii) |
+| `entry:overtaking_gives_way` | `rule:13a` | 13(a) |
+| `entry:narrow_channel_small_or_sail` | `rule:9b` | 9(b) |
+| `entry:narrow_channel_fishing` | `rule:9c` | 9(c) |
+| `entry:traffic_lane_fishing` | `rule:10i` | 10(i) |
+| `entry:traffic_lane_small_or_sail` | `rule:10j` | 10(j) |
+| `entry:steady_bearing` | `rule:7d_i` | 7(d)(i) |
+| `entry:sail_port_tack_gives_way` | `rule:12a_i` | 12(a)(i) |
+| `entry:sail_windward_gives_way` | `rule:12a_ii` | 12(a)(ii) |
+| `entry:sail_port_tack_uncertain_gives_way` | `rule:12a_iii` | 12(a)(iii) |
+| `entry:overtaking` | `rule:13b` | 13(b) |
+| `entry:being_overtaken` | `rule:13b` | 13(b) |
+| `entry:overtaking_until_past_and_clear` | `rule:13d` | 13(d) |
+| `entry:head_on` | `rule:14b` | 14(b) |
+| `entry:crossing` | `rule:15a:crossing` | 15(a) |
+| `entry:crossing_gives_way` | `rule:15a:keep_out_of_the_way` | 15(a) |
+| `entry:mooring_buoy` | `rule:30a:mooring_buoy` | 30(a) |
+| `entry:mooring_buoy_under_50m` | `rule:30b:mooring_buoy` | 30(b) |
+
+## Consequences
+
+- One pass, one commit: `data/applicability.json`, both fixture files,
+  `data/geometry.json`, `data/images.json`, `data/facts.json`,
+  `data/rules.json`, the schemas, the suite and the living docs. The
+  schema `$defs` that named the type follow the noun: `entryId` is
+  `ruleId`, `entryIdList` is `ruleIdList`.
+- Two entries may still share a cite — `rule:24a_i` and
+  `rule:24a_i:exceeds_200m`, the two halves of 15(a), the two mooring-buoy
+  deltas. What they never share is an id, and the third segment says which
+  norm out of the paragraph the entry carries.
+- Earlier ADRs and closed questions cite entries by the superseded names;
+  the table above is the map and stays in this file permanently. ADR 0006
+  carries a dated note that its identifier-diff half is gone.
+- `represented_paragraphs` is now a second list of records that look like
+  entries, differing only in carrying no `when`. Folding it into `entries`
+  with a `care`/`meta` category is the obvious follow-up and is not done
+  here.
+- Open, and not ruled: whether `fact:rule18_class` should be renamed. It
+  carries a rule number inside a fact name, which is the shape this ADR
+  moved *entry* ids towards and says nothing about for facts. Left visibly
+  open.
+- An encounter with more than two vessels is issue #135; nothing in this
+  scheme is aimed at it, and a third subject would need a segment none of
+  these ids have.

package/docs/budgets.json

@@ -2,6 +2,7 @@
   "$comment": "Prose budgets enforced by prose-budget (the engine in dotfiles .local/bin), run locally by npm test and in CI by the shared workflow. Raising a number or adding an exception is a deliberate, reviewable diff.",
   "lines": {
     "README.md": 360,
+    "docs/normative-language.md": 130,
     "AGENTS.md": 200,
     "CLAUDE.md": 10,
     "docs/requirements.md": 1500,
@@ -18,7 +19,10 @@
     "required": true,
     "pending": [],
     "docs/adr/0013-corpus-files-with-editions.md": 95,
-    "docs/timeline.md": 130
+    "docs/adr/0014-engine-interface-owned-by-colregs.md": 110,
+    "docs/adr/0015-rule-ids-are-paragraph-keys.md": 210,
+    "docs/timeline.md": 130,
+    "docs/maritime-sources.md": 130
   },
   "json_prose": {
     "targets": [
@@ -55,14 +59,10 @@
       "data/applicability.json#/entries/62/note",
       "data/applicability.json#/entries/63/note",
       "data/applicability.json#/entries/64/note",
-      "data/applicability.json#/entries/64/gap",
       "data/applicability.json#/entries/65/note",
-      "data/applicability.json#/entries/65/gap",
       "data/applicability.json#/entries/66/note",
       "data/applicability.json#/entries/67/note",
       "data/applicability.json#/entries/68/note",
-      "data/applicability.json#/entries/68/gap",
-      "data/applicability.json#/entries/69/note",
       "data/facts.json#/derived/note",
       "data/facts.json#/derived/fact:rule18_class/note",
       "data/facts.json#/derived/fact:rule18_class/decode/1/note",
@@ -134,16 +134,6 @@
       ]
     },
     "grandfathered": [
-      {
-        "file": "data/applicability.json",
-        "hash": "447b3984d57b",
-        "match": "PR #24"
-      },
-      {
-        "file": "data/applicability.json",
-        "hash": "5ff9d39319b8",
-        "match": "PR #24"
-      },
       {
         "file": "docs/conventions.md",
         "hash": "d1f1ed997431",

package/docs/identifiers.md

@@ -17,10 +17,12 @@ citation: `27(a)(i)` is what a mariner, a lawyer and a court all write, and
 what a consumer stores when it records why a light was shown. Prefixing it
 would put a package-local token in front of a reference that belongs to the
 Convention rather than to this repository, and would make a stored citation
-unreadable outside the tool that stored it. Entry ids are derived from
-paragraph paths (below) and inherit the same transparency for the same
-reason. Paragraph-keying is argued in ADR 0001 and required by
-REQ-MODEL-4; nothing here reopens either.
+unreadable outside the tool that stored it. Rule ids sit beside this class
+rather than in it: `rule:13b` is *shaped* like the cite it was minted from,
+but it is a name in a namespace and a consumer reads the paragraph out of
+`cite`, never out of the id (ADR 0015).
+Paragraph-keying is argued in ADR 0001 and required by REQ-MODEL-4; nothing
+here reopens either.
 
 **Vocabulary identifiers carry a type prefix.** These names are this
 package's own — nothing in COLREGS calls anything `masthead` or `nuc`. They
@@ -35,6 +37,7 @@ resolves that collision by construction rather than by convention.
 
 | form | class | examples |
 |---|---|---|
+| `rule:<paragraph-slug>` | applicability entries (`data/applicability.json`) | `rule:30a`, `rule:24a_i:exceeds_200m`, `rule:15a:keep_out_of_the_way` |
 | `light:<id>` | light definitions (`data/lights.json`) | `light:masthead`, `light:sidelight_starboard`, `light:all_round` |
 | `fact:<key>` | fact keys — the input vocabulary (`data/facts.json`) | `fact:activity`, `fact:length_m`, `fact:making_way`, `fact:on_mooring_buoy` |
 | `<fact>:<value>` | values of an enumerated fact | `activity:nuc`, `position:anchored`, `propulsion:sail`, `obstruction_side:port` |
@@ -257,21 +260,21 @@ of them; the departure from the table is recorded in ADR 0005's pencil log and
 in `Q-40`.
 
 **Who governs over Rule 12.** 12(a)'s subjects are "two sailing vessels",
-which is 3(c), so `12a1`–`12a3` gate on `fact:propulsion` and not on the Rule
+which is 3(c), so the three Rule 12 entries gate on `fact:propulsion` and not on the Rule
 18 rank — a fishing vessel under sail is a sailing vessel. Where Rule 18 also
-ranks the pair, its entry displaces Rule 12's: `18b1`–`18b3` and `18c1`–`18c2`
+ranks the pair, its entry displaces Rule 12's: the three 18(b) entries and the two 18(c) entries
 carry `rel:overrides` against all three, because Rule 18's opening words
-except Rules 9, 10 and 13 and nothing else. `13a` overrides them for the same
+except Rules 9, 10 and 13 and nothing else. `rule:13a` overrides them for the same
 reason it overrides Rule 18 — 13(a) is "notwithstanding" the rest of Sections
 I and II. The test that pins the relation asserts both reasons from
 `rules.json`, so the data cannot keep an override after losing the words.
 
 **And over Rule 15, the same way.** 15(a)'s subjects are "two power-driven
-vessels", which is 3(b), so `15a-give-way` gates on `fact:propulsion` and on
+vessels", which is 3(b), so `rule:15a:keep_out_of_the_way` gates on `fact:propulsion` and on
 no Rule 18 rank either — a vessel engaged in fishing, or not under command,
 whose machinery is in use is a power-driven vessel. It used to negate the four
 ranks in its own predicate, which said the same thing in the one place a test
-could not see the reason; `18a1`–`18a3`, `18c1`–`18c2` and `18f1` now carry
+could not see the reason; the 18(a)(i)–(iii) entries, the two 18(c) entries and `rule:18f_i` now carry
 `rel:overrides` against it instead. The derived half of the test is what makes
 that checkable: a Rule 18 entry meets Rule 15 when it assigns a helm role and
 neither subject is gated to a sailing vessel, and every such entry must carry
@@ -292,53 +295,48 @@ that is Rule 18's partial order rather than a gap in the table.
 — keep well clear, and avoid impeding navigation. The vocabulary cannot
 separate them and does not pretend to.
 
-### Two-subject entry ids
+### Two-subject rule ids
 
-Entry ids stay citation-derived, exactly as below: `18a1` is 18(a)(i), `9c` is
-9(c), `8f3` is 8(f)(iii). Where a paragraph's subject is disjunctive — 9(b) is
-"a vessel of less than 20 metres in length **or** a sailing vessel", and a
-`when` is a conjunction — the paragraph takes two entries and the suffix names
-the half: `9b-small` and `9b-sail`, `10j-small` and `10j-sail`. That is the
-same rule the `-m2`/`-mw`/`-anc` suffixes below follow: name what
-distinguishes them, in terms a reader with the rule text in front of them can
-find.
+A two-subject entry is keyed on its paragraph like any other (below):
+`rule:18a_i` is 18(a)(i), `rule:9c` is 9(c), `rule:8f_iii` is 8(f)(iii). No
+subject segment appears in an id: every entry is evaluated from own's side,
+and where the paragraph classifies the pair rather than one vessel the entry
+reads both subjects inside one predicate — `rule:13b` is 13(b) whichever
+vessel is coming up. Where a paragraph's subject is disjunctive — 9(b) is
+"a vessel of less than 20 metres in length **or** a sailing vessel" —
+`any_of` carries the disjunction inside one entry, `rule:9b`.
 
-## Entry ids
+## Rule ids
 
-An entry id is derived from the paragraph path its entry cites, lowercased
-with the parentheses dropped and roman sub-paragraph numerals written as
-arabic digits:
+An entry id is a paragraph key in the `rule:` namespace: `rule:` plus the
+cite with its punctuation dropped. ADR 0015 (Solace, 2026-09-16) made the
+change and carries the table from the ids it replaced; the rule for minting
+a new one is here.
 
-| paragraph path | entry id |
-|---|---|
-| Rule 28 (one paragraph) | `28` |
-| `23(b)` | `23b` |
-| `25(d)(ii)` | `25d2` |
-| `23(a)(iii)`–`(iv)`, one entry | `23a34` |
-
-Where one paragraph produces more than one entry, a hyphenated suffix names
-what distinguishes them. The suffixes are **not** drawn from a single
-scheme, because the paragraphs they split do not divide on a single axis:
-
-| suffix | means | example |
+| paragraph | rule id | why that id |
 |---|---|---|
-| `-m2` / `-m3` | two or three masthead lights | `24a-m2`, `24a-m3` |
-| `-rest` | the remainder of the rule's requirements once the split ones are taken out | `24a-rest` |
-| `-id` | the identity lights: the all-round group that says *what the vessel is* | `26b-id`, `27a-id`, `27b-id` |
-| `-mast` | the masthead light the paragraph adds on top of the identity lights | `26b-mast` |
-| `-mw` | the making-way half of a rule that lights differently when moving through the water | `26b-mw`, `27a-mw`, `27b-mw` |
-| `-gear` | the light indicating the direction of outlying gear | `26c-gear` |
-| `-anc` | the at-anchor branch | `27b-anc` |
-| `-anchor` / `-red` | 30(d)'s two halves: the anchor lights it requires, and the two red all-round lights of a vessel aground | `30d-anchor`, `30d-red` |
-
-This was reviewed and kept as it stands. The alternative — a uniform
-ordinal suffix, `27a-1` / `27a-2` — would be self-consistent and completely
-opaque: it tells a reader with the rule text in front of them nothing, in
-exchange for no gain to a machine, which only ever compares entry ids for
-equality. `24a-m2` / `24a-m3` are worth calling out in particular, because
-the two-or-three masthead split is stated in 24(a)(i) itself — the
-cardinality is in the law, not a modelling convenience of this package, and
-the suffix names something the reader can go and find.
+| 30(a) | `rule:30a` | the bare slug of the cite: rule number, paragraph letter attached |
+| 27(a)(i) | `rule:27a_i` | each roman subparagraph joined with `_` |
+| 23(a)(iii)-(iv) | `rule:23a_iii_iv` | a span of subparagraphs, joined the same way |
+| 24(a)(i), tow over 200 m | `rule:24a_i:exceeds_200m` | a further norm out of the same paragraph, named in the text's own words |
+| 15(a), the duty | `rule:15a:keep_out_of_the_way` | which half of a fused deeming-and-duty sentence this entry carries |
+| 30(a), US inland | `rule:30a:mooring_buoy` | a jurisdiction delta named by its difference; the jurisdiction stays a field |
+
+A bare id is the paragraph's principal norm. A third segment is added only
+where the text yields a second norm from the same paragraph, and it is named
+in the words of the text, not in what the entry produces. A number may appear
+there only when the Convention states the threshold itself (`exceeds_200m` is
+24(a)(i)'s).
+
+**The id is opaque.** It looks like a citation and it is not one: a consumer
+that wants "Rule 24(a)(i)" reads `cite`, and never splits an id to find a
+paragraph. `cite` is the field that moves when the package reads the Rules
+better — `14a` became `14b` once already — and the id resembling it is a
+convenience for the human reading a trace, nothing the data promises. Two
+entries may share a cite; they never share an id.
+
+`represented_paragraphs` take the same prefix and the same shape
+(`rule:2a` for 2(a)). They are not entries and nothing references them.
 
 ## Derived facts
 

package/docs/maritime-sources.md

@@ -0,0 +1,58 @@
+# Maritime sources — case law and incident analysis
+
+Decisions and commentary on how the Rules are conventionally read, and
+collision forensics showing how they fail in the water.
+
+A case is evidence that a reading is or is not conventional. It never becomes
+a proposition in `docs/part-b-invariants.md`, which holds no maritime doctrine
+by design. Consult these where a `Q-` in `docs/requirements.md` §11 turns on a
+question the rule text leaves open.
+
+## Case law
+
+- **Monford Management Ltd v Afina Navigation Ltd ("KIVELI" c/w "AFINA I") [2025] EWHC 1185 (Admlty)**. Bryan J, Admiralty Court; permission to appeal refused, [2025] EWHC 1210. When a Section II classification arms and how long it persists — `Q-51` and `Q-52`. Held: Rule 14 applies once risk of collision arises, not on geometry alone, and risk of collision was found on Rule 7(d)(i) steady bearing plus an unsafe CPA; once armed, the classification persists until the risk has passed, unaffected by later course changes. The court rejected the submission that a head-on at C-22 had become a crossing by C-6 as the bearing opened. Reaches Rule 13 by analogy only; silent on overtaking.
+  <https://caselaw.nationalarchives.gov.uk/ewhc/admlty/2025/1185> · case note by Nigel Cooper KC, counsel for AFINA I: <https://www.quadrantchambers.com/sites/default/files/2025-05/avoiding_a_head-on_collision_-_it_is_not_just_about_the_side_lights.pdf>
+- **Evergreen Marine (UK) Ltd v Nautical Challenge Ltd ("Ever Smart" / "Alexandra 1") [2021] UKSC 6**. Frames Section II as a scheme about steady-bearing *collision* situations, with Rule 13 inside that taxonomy ([56]–[57]); leans against treating an engaged rule as inapplicable ([68]); describes Rule 17's obligations as qualified stages, predicates on the current state, with keep-course-and-speed accommodating manoeuvres such as slowing to pick up a pilot ([61]–[62]). Not asked when Rule 13 arms, and did not decide it. Separately, at [60] and [66]–[67], settles `Q-23`'s asymmetry: Rule 2(a) is a standing responsibility clause that authorises nothing, while Rule 2(b) is a conjunctive test — special circumstance *and* immediate danger — and rejects Rule 2 as a gap-filler for the steering rules.
+  <https://caselaw.nationalarchives.gov.uk/uksc/2021/6>
+- **Crowley Marine Services Inc. v. Maritrans Inc., 447 F.3d 719 (9th Cir. 2006)**. `Q-23`: the burden of justifying a Rule 2(b) departure falls on the departing vessel, and the departure must respond to an immediate danger already created — a pre-emptive departure does not qualify (n.6).
+  <https://cdn.ca9.uscourts.gov/datastore/opinions/2006/05/08/0435724.pdf>
+
+## Commentary and guidance
+
+- **Kemp — *When Do Collision Regulations Begin to Apply?* (Journal of Navigation)**. A judicial split on the antecedent question: some decisions hold the steering and sailing rules begin at risk of collision, others that they apply just before it, risk of collision being the thing to be avoided.
+  <https://www.cambridge.org/core/journals/journal-of-navigation/article/abs/when-do-collision-regulations-begin-to-apply/E6DBCD8A6ABC43FA88B5E6CB3ABF807C>
+- **eCOLREGs — overtaking and crossing on the high seas**. States the broad reading of Rule 13(d) as conventional: an overtaking vessel "maintains overtaking status and cannot transition into a crossing or head-on situation until completely past and clear".
+  <https://advanced.ecolregs.com/index.php?option=com_k2&view=item&id=172>
+- **Nautical Institute — *Action by the Stand-On Vessel*** (Seaways case study). The stand-on vessel's stages as taught; does not reach whether they are reversible.
+  <https://www.nautinst.org/resources-page/200115-action-by-the-stand-on-vessel.html>
+- **USCG Navigation Rules (Amalgamated)**. <https://www.navcen.uscg.gov/navigation-rules-amalgamated>
+
+## Marine incident analysis
+
+Collision forensics. Radar misinterpretation, mismatched turn decisions and
+ambiguous give-way/stand-on roles are what the Rules are written against.
+
+- Garzke, Simpson — *The Loss of Andrea Doria: A Marine Forensic Analysis* (Marine Technology Society Journal 46(6), 2012). Reconstructs the 1956 Andrea Doria–Stockholm collision from radar, navigation and rules-of-the-road evidence.
+  <https://www.ingentaconnect.com/content/mts/mtsj/2012/00000046/00000006/art00008> · <https://onepetro.org/JSPD/article/26/02/98/172277/The-Loss-of-Andrea-Doria-A-Marine-Forensic>
+- British Wreck Commissioner (Lord Mersey) — *Report on the Loss of the Titanic* (1912). Excessive speed through a known ice field despite wireless ice warnings — a Rule 6 case, not give-way/stand-on.
+  <https://www.titanicinquiry.org/BOTInq/BOTReport/botRep01.php>
+- Halpern — *Strangers on the Horizon: Titanic and Californian – A Forensic Approach* (2019). Reconstruction of the Titanic–Californian near-encounter: lookout, distress-signal and stand-on/give-way failures. Book only.
+  <https://www.amazon.com/STRANGERS-HORIZON-Californian-Forensic-Approach/dp/1702121984>
+- MAIB (for the Isle of Man Ship Registry) — *Report on the investigation of
+  the collision between the bulk carrier Polesie and the general cargo ship
+  Verity* (Report No 5/2026, February 2026). German Bight TSS, 24 October
+  2023; *Verity* sank with five fatalities. Analysis covers Rules 5, 6, 7, 8,
+  15, 16 and 17(a)(ii)/(b) only — it does not reach Rule 2(b), correcting an
+  earlier claim that it paired 17(b) with 2(b) at closest quarters.
+  <https://www.bahamasmaritime.com/wp-content/uploads/2026/02/2026-5-Polesie-Verity-ReportAndAnnexes.pdf>
+- IMO GISIS Marine Casualties and Incidents module. Not a paper but a source class: the mandatory-reporting database of marine safety investigation reports. Ground truth for real COLREGS-relevant incidents.
+  <https://www.imo.org/en/OurWork/IIIS/Pages/Marine-Safety-Investigation-reports.aspx>
+
+## Known gaps
+
+- `Q-23`: *The Bywell Castle* and *Boy Andrew v St Rognvald* are unread, and no
+  case was found holding a Rule 2(b) departure justified on draught,
+  manoeuvrability, shoal water, a lee shore, set, visibility or sea state.
+- Two standard texts — Cockcroft & Lameijer, *A Guide to the Collision Avoidance Rules*, and Farwell's *Rules of the Nautical Road* — are not online. Either may settle how the stages of a close-quarters encounter are divided, and whether they are treated as irreversible.
+- Several of the questions in `docs/requirements.md` §11 appear unlitigated: overtaking geometry with no risk of collision, an overtaking situation becoming a head-on, resumption of course by a stand-on vessel that has acted, and the fate of accumulated Section II state across a visibility transition.
+- BAILII refuses automated access. Use the National Archives Find Case Law service: <https://caselaw.nationalarchives.gov.uk/>

package/docs/normative-language.md

@@ -0,0 +1,103 @@
+# Normative language — how "shall", "may" and friends are used here
+
+Status: **ink**, 2026-09-05. Reviewed and accepted by the maintainer; this is the
+standing decision until an ADR supersedes it.
+
+## The decision
+
+Two vocabularies, kept apart on purpose:
+
+1. **Our own requirements** (`docs/requirements.md` here, and any spec in
+   this repo or in colregs-engine) use **MUST / MUST NOT / SHOULD / SHOULD NOT / MAY** in capitals,
+   with the meaning given by [RFC 2119] as clarified by [RFC 8174]: only
+   the capitalised words carry that meaning. Lower-case "must" or "should" in our prose is
+   ordinary English.
+2. **The data follows the Convention.** The `modality` field in
+   `data/applicability.json` holds a lower-case token derived from the
+   Convention's own verb for that paragraph: `shall`, `may`, `shall-not`,
+   `shall-if-practicable`, `shall-not-impede`, `conditional`, `exempt`.
+   These are *not* RFC 2119 keywords. They are normalised from treaty text,
+   and the verbatim paragraph sits next to them in `data/rules.json` so a
+   reader can check the token against the words. Two tokens are not verbs:
+   `conditional` means the verb itself turns on a fact, and the entry's
+   `modality_by` table says which verb applies when (Rule 23(a)(ii) is
+   `shall` at 50 m and above, `may` below); `exempt` means the paragraph
+   lifts a duty another paragraph imposes, named by `rel:exempts` (Rule
+   30(e) for small vessels at anchor). Use `conditional` only when the
+   Convention states the threshold in the paragraph; use `exempt` only when
+   the paragraph's verb is "shall not be required" or equivalent.
+
+So a capitalised MUST is a claim about the package. A lower-case `shall` in
+the data is a claim about what COLREGS says. Nothing in the repo maps one
+onto the other.
+
+## Where COLREGS will surprise an RFC reader
+
+If you learned obligation words from RFCs, three things about the
+Convention are counterintuitive. The data model follows the Convention,
+not the RFC, on each.
+
+- **There is no SHOULD tier.** RFC 2119 gives you a recommended-but-waivable
+  level. COLREGS uses "should" once in the Rules (8(b); the Annexes are not checked) and
+  nowhere defines it as a weaker rank of duty. Instead the Convention
+  **softens a duty with a condition on it, not with a weaker verb**:
+  "so far as possible", "if the circumstances of the case admit", "if
+  practicable". The data carries that as `shall-if-practicable`, a
+  qualified obligation, rather than inventing a `should`. One token covers
+  several phrasings ("so far as possible", "if the circumstances of the
+  case admit"); whether the exact qualifier deserves its own field beside
+  `modality` is question Q-31, still open.
+- **`may` is a lawful alternative, not an optional extra.** In RFC 2119 a
+  MAY is something nobody may depend on. In COLREGS a `may` display is one
+  of several complete, lawful options, and the paragraph says how it
+  relates to the others. Rule 25(b) lets a small sailing vessel *combine*
+  the 25(a) lights into one masthead lantern, so it replaces 25(a) and the
+  data records that with `rel:in_lieu_of`. Rule 25(c) lets any sailing
+  vessel show red-over-green *in addition to* 25(a), so it is
+  `rel:includes`, and it may not be shown with the 25(b) lantern, so the
+  two `rel:excludes` each other. The data keeps every lawful option with
+  its own modality and never picks one.
+- **`shall not impede` is its own kind of duty.** It has no RFC analogue.
+  It is weaker than "shall keep out of the way", and Rule 8(f) says the
+  other vessel keeps all her own duties too. Where a paragraph's verb is
+  "shall not impede" (Rules 9(b), 9(c), 10(i), 10(j)) that is its
+  `modality`; the same duty is also recorded as an `effect` on the vessel,
+  so a paragraph with a different verb can still impose it (Rule 18(d)(i)).
+
+`shall not` (a prohibition) and `shall` (an obligation) mean what an RFC
+reader expects.
+
+## What we defer to, and for what
+
+| Question | Defer to |
+|---|---|
+| What MUST / SHOULD / MAY mean in our own specs | [RFC 2119], [RFC 8174]; the W3C's [RfcKeywords] page shows how other standards cite them |
+| What `shall` / `may` / `shall not` mean in the data | The paragraph text in `data/rules.json`; no external standard redefines it |
+| Which edition of COLREGS, and which amendments, the data encodes | `docs/adr/0001` and the provenance requirements (`REQ-PROV-*`); this note says nothing about editions |
+| How standards bodies read `shall`/`should`/`may`/`can` in their own documents | [ISO/IEC Directives, Part 2], Clause 7. Not adopted here; listed because marine-standards readers will assume it |
+
+The gap between ISO's `should` (a recommendation) and COLREGS's conditional
+`shall` is exactly the first surprise above. None of this is legal advice:
+the data records what the text says, not how a court would read it.
+
+## For reviewers
+
+A pull request that adds or changes an entry is held to this note. Check:
+
+- the `modality` token matches the paragraph's own verb, and a
+  practicability phrase ("so far as possible", "if the circumstances of the
+  case admit", "if practicable") becomes `shall-if-practicable`, never a
+  new `should`;
+- a `may` entry says how it relates to the displays it is an alternative
+  to: `rel:in_lieu_of` only where the paragraph replaces another display,
+  `rel:includes` where it adds to one, `rel:excludes` where the two may not
+  be shown together;
+- a "shall not impede" paragraph carries the `shall-not-impede` effect,
+  whatever its `modality`;
+- new prose in `requirements.md` capitalises the RFC keywords it means and
+  leaves ordinary "must" and "should" in lower case.
+
+[RFC 2119]: https://www.rfc-editor.org/rfc/rfc2119
+[RFC 8174]: https://www.rfc-editor.org/rfc/rfc8174
+[RfcKeywords]: https://www.w3.org/wiki/RfcKeywords
+[ISO/IEC Directives, Part 2]: https://www.iso.org/sites/directives/current/part2/index.xhtml