colregs 0.2.4 → 0.3.1

package/docs/budgets.json

@@ -1,12 +1,14 @@
 {
   "$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": 200,
-    "AGENTS.md": 122,
+    "README.md": 360,
+    "docs/normative-language.md": 130,
+    "AGENTS.md": 200,
     "CLAUDE.md": 10,
     "docs/requirements.md": 1500,
     "docs/identifiers.md": 450,
     "docs/part-b-invariants.md": 950,
+    "docs/adr/0001-name-and-jurisdiction-model.md": 280,
     "docs/adr/0007-rule26-overrides-and-aground.md": 90,
     "docs/adr/0008-mooring-buoy-modifier.md": 90,
     "docs/adr/0009-data-version-stamp.md": 90,
@@ -15,11 +17,17 @@
     "docs/adr/0012-trace-and-rule2-departure-api.md": 203,
     "docs/verification/2026-09-09-text-slug-straw-man.md": 270,
     "required": true,
-    "pending": []
+    "pending": [],
+    "docs/adr/0013-corpus-files-with-editions.md": 95,
+    "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": [
       "data/*.json",
+      "data/text/**/*.json",
       "fixtures/*.json"
     ],
     "keys": [
@@ -51,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",
@@ -86,6 +90,7 @@
       "AGENTS.md",
       "CLAUDE.md",
       "data/*.json",
+      "data/text/**/*.json",
       "fixtures/*.json",
       "test/*.mjs",
       "docs/**/*.md"
@@ -96,6 +101,7 @@
         "AGENTS.md",
         "CLAUDE.md",
         "data/*.json",
+        "data/text/**/*.json",
         "fixtures/*.json",
         "test/*.mjs"
       ],
@@ -104,6 +110,7 @@
         "AGENTS.md",
         "CLAUDE.md",
         "data/*.json",
+        "data/text/**/*.json",
         "fixtures/*.json",
         "test/*.mjs"
       ],
@@ -112,6 +119,7 @@
         "AGENTS.md",
         "CLAUDE.md",
         "data/*.json",
+        "data/text/**/*.json",
         "fixtures/*.json",
         "test/*.mjs"
       ],
@@ -120,21 +128,12 @@
         "AGENTS.md",
         "CLAUDE.md",
         "data/*.json",
+        "data/text/**/*.json",
         "fixtures/*.json",
         "test/*.mjs"
       ]
     },
     "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",
@@ -155,6 +154,7 @@
       "CLAUDE.md",
       "docs/**/*.md",
       "data/*.json",
+      "data/text/**/*.json",
       "fixtures/*.json"
     ]
   },

package/docs/gates.json

@@ -36,9 +36,9 @@
       "declined_in": "docs/adr/0003-language-as-a-dimension.md",
       "closing_event": "first-non-english-corpus",
       "trigger": "a jurisdiction publishing two editions in force concurrently",
-      "status": "open",
-      "settled_by": null,
-      "note": "Due at translation #1, not at 1.0."
+      "status": "adopted",
+      "settled_by": "docs/adr/0013-corpus-files-with-editions.md",
+      "note": "Re-taken and adopted ahead of its due date (translation #1) — ADR 0013 introduces the edition registry directly."
     },
     {
       "id": "GATE-3",

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

package/docs/part-b-invariants.md

@@ -34,9 +34,9 @@ suffix naming what distinguishes them.
 - Insertion appends a suffix and never renumbers; a suffix names something and
   is not an ordinal (`REQ-INV-2`).
 - The paragraph is the unit (ADR 0001): an invariant reading several takes the
-  id of the one stating its operative content, as entry `14b` does.
+  id of the one stating its operative content, as entry `rule:14b` does.
 - `INV-` is a type prefix on a citation-derived name — the one departure from
-  `docs/identifiers.md`, because `13a` is already an entry id. Jurisdiction is a
+  `docs/identifiers.md`, because `rule:13a` is already an entry id. Jurisdiction is a
   dimension (`REQ-SCOPE-2`, `Q-8`); only `intl` is populated.
 
 ---
@@ -82,10 +82,10 @@ not overtaking); its edges are the forward edges of Rule 21(c)'s sternlight
 arc, which 13(b)'s second limb states in light terms.
 
 - **Undetermined term.** "Coming up with" is a speed comparison the model cannot
-  express (`Q-46`); `13b-overtaking` substitutes `pair:geo:tcpa_s > 0`, which
+  express (`Q-46`); `rule:13b` substitutes `pair:geo:tcpa_s > 0`, which
   admits a pair closing because the vessel ahead stopped. This states the rule.
 - **Not stated by 13(b).** Risk of collision: `Q-50`.
-- Entries: `13b-overtaking`, `13b-overtaken`;
+- Entries: `rule:13b`;
   `situation.constants.overtaking_sector_from_deg`/`_to_deg` (ink). Settled by
   P2.2's Alloy sector model: a partition, or a bearing that falls in both.
 
@@ -100,9 +100,11 @@ overtaking vessel bears forward of her beam.
 
 - **Why separate.** A formalisation carrying encounter type per vessel
   classifies the overtaken side as a crossing, two types on one pair.
-- Entries: `13b-overtaking`, `13b-overtaken`, each other's `when` with subjects
-  swapped. Settled by P4.2 carrying the type on the pair and TLC finding no
-  state where the subjects disagree.
+- **2026-09-16.** The two-entry form this section recorded is reversed by
+  ADR 0015 as rewritten: 13(b) is one symmetric entry, the same sector object
+  read on either subject under `any_of`. The invariant is unchanged.
+- Entries: `rule:13b`. Settled by P4.2 carrying the type on the pair and TLC
+  finding no state where the subjects disagree.
 
 ### INV-13a — the overtaking vessel keeps out of the way
 
@@ -116,7 +118,7 @@ roles displace any role Rules 4–18 would otherwise assign to either vessel.
 well as Rules 14 and 15.
 
 - **Not stated by 13(a).** Risk of collision: `Q-50`.
-- Entries: `13a`, overriding all eleven Rule 18 and all three Rule 12 entries.
+- Entries: `rule:13a`, overriding all eleven Rule 18 and all three Rule 12 entries.
   Settled by P4.2's role assignment: the override is or is not needed to keep
   "never both give-way" true.
 
@@ -142,8 +144,8 @@ until own is finally past and clear, the encounter type of the pair is
   model's is its segmentation, and no bearing or range is invented here.
 - **Readings in doubt.** Two: what arms the latch, `Q-51`; what it forbids,
   `Q-52`.
-- Entries: `13d`, reading `own`/`other:hist:was_overtaking` and no geometry; the
-  `was_overtaking: false` gates on `14b`, `15a-crossing`, `15a-give-way`
+- Entries: `rule:13d`, reading `own`/`other:hist:was_overtaking` and no geometry; the
+  `was_overtaking: false` gates on `rule:14b`, `rule:15a:crossing`, `rule:15a:keep_out_of_the_way`
   implement `Q-52`'s *broad* reading. Settled by `Q-51`, `Q-52`, then TLC on a
   three-state trace of an overtaking drawing out onto the bow.
 
@@ -159,7 +161,7 @@ the duty by its second clause, and a formalisation deriving role from encounter
 type alone cannot distinguish `Q-52`'s readings.
 
 - **State remembered.** As `INV-13d`.
-- Entries: `13a`'s `any_of` second limb, `own:hist:was_overtaking: true` — role
+- Entries: `rule:13a`'s `any_of` second limb, `own:hist:was_overtaking: true` — role
   asserted from the latch directly, keeping the limbs separable. Settled by
   `Q-52`.
 
@@ -186,7 +188,7 @@ in [0°, 11.25°] ∪ [348.75°, 360°).
   that way.
 - **Not formalised.** The night and day observation limbs are stated as the
   geometry they encode; a vessel that cannot see the lights has 14(c).
-- Entries: `14b`. Settled by `INV-13b`'s partition sweep plus a decision on the
+- Entries: `rule:14b`. Settled by `INV-13b`'s partition sweep plus a decision on the
   constant.
 
 ### INV-14a — both vessels alter to starboard
@@ -205,8 +207,8 @@ way; both are directed to act, and the duty is symmetric.
 - **Why it matters formally.** The one Section II encounter with no `stand-on`
   vessel, and why `INV-17a1-scope` has content.
 - Entries: none; `conduct`, in `known_omissions`, no conduct shape (`Q-45`);
-  `14a` is retired in `data/deprecated-identifiers.json`. Settled by the first
-  conduct monitor.
+  `14a` was never a name and is gone with the rest of the citation-derived ids
+  (ADR 0015). Settled by the first conduct monitor.
 
 ---
 
@@ -228,7 +230,7 @@ encounter type is `crossing` exactly when it is neither `overtaking` under
 - **Known incompleteness.** Two sailing vessels get no encounter type (Rules 14
   and 15 are gated on power, Rule 12 has no deeming paragraph): the Rules'. A
   pair with the history fact absent gets none: the model's (`Q-43`).
-- Entries: `15a-crossing`.
+- Entries: `rule:15a:crossing`.
 
 ### INV-15a-give-way — the vessel with the other to starboard gives way
 
@@ -241,7 +243,7 @@ other holds `stand-on`.
 - **Undetermined term.** "On her own starboard side" has no sector in the
   paragraph; the data reads `own:geo:rel_bearing_deg` in (0°, 112.5°], its upper
   edge 13(b)'s constant, so it is checkable against the partition.
-- Entries: `15a-give-way`, plus six `rel:overrides` from Rule 18 entries, since
+- Entries: `rule:15a:keep_out_of_the_way`, plus six `rel:overrides` from Rule 18 entries, since
   Rule 18's chapeau excepts Rules 9, 10 and 13 and no others.
 
 ### INV-15a-single — at most one give-way vessel in a crossing
@@ -277,7 +279,7 @@ advancing position.
   segment ("ahead of" a moving vessel), and the state the role attached.
 - **Undetermined term.** "If the circumstances of the case admit" has nowhere to
   live — `modality` is one closed value, an action has no `effect` — `Q-31`.
-- Entries: none; a `gap` on `15a-give-way`.
+- Entries: none; a `gap` on `rule:15a:keep_out_of_the_way`.
 
 ---
 
@@ -443,7 +445,7 @@ discharge her obligation.
 - **Why separate.** The natural automaton takes the give-way duty as an input to
   its transitions; 17(d) says the arrow does not run back, so model two
   obligations holding concurrently, not one machine with one obligation.
-- Entries: none; nearest is 8(f)(ii)'s parallel for `shall-not-impede`, `8f3`.
+- Entries: none; nearest is 8(f)(ii)'s parallel for `shall-not-impede`, `rule:8f_iii`.
 
 ### INV-17-phases — the phase structure
 
@@ -485,9 +487,9 @@ governs.
 - **Why both directions.** "To nothing else" is what runs the `rel:overrides`
   edges from Rule 18 *to* Rules 12 and 15; got wrong once, found by a sweep
   (`Q-40`).
-- Entries: overrides on `13a` against all Rule 18 and Rule 12 entries; on
-  `18a1`–`18a3`, `18c1`–`18c2`, `18f1` against `15a-give-way`; on the Rule 18
-  entries that can meet two sailing vessels against `12a1`–`12a3`; a derived
+- Entries: overrides on `rule:13a` against all Rule 18 and Rule 12 entries; on
+  the 18(a)(i)–(iii) entries, the two 18(c) entries, `rule:18f_i` against `rule:15a:keep_out_of_the_way`; on the Rule 18
+  entries that can meet two sailing vessels against the three Rule 12 entries; a derived
   check asserts the hand-list of six against Rule 15 is complete.
 
 ### INV-18-order — the rank order
@@ -510,7 +512,7 @@ The subject holds `give-way`; the object `stand-on`.
   (`Q-32`) is the model's decode onto these ranks. A vessel constrained by her
   draught is a power-driven vessel for 18(a) and is ranked by it.
 - **Not stated by Rule 18.** Risk of collision and encounter type: `Q-50`.
-- Entries: `18a1`–`18a4`, `18b1`–`18b3`, `18c1`–`18c2`.
+- Entries: the four 18(a) entries, the three 18(b) entries, the two 18(c) entries.
 
 ### INV-18-partial — the order is partial, and the gaps are the Rules'
 
@@ -542,7 +544,7 @@ discharging `INV-16` requires of her.
 
 - **Why stated.** Read as a condition on the antecedent, it gives a roleless
   pair exactly when compliance is hard and the roles matter.
-- Entries: `18c1`, `18c2`, modality `shall-if-practicable` with effect
+- Entries: `rule:18c_i`, `rule:18c_ii`, modality `shall-if-practicable` with effect
   `give-way`/`stand-on` — `Q-31`'s shape, resolved only because the duty is a
   role.
 
@@ -563,8 +565,8 @@ is not relieved (8(f)(ii)).
   protected vessel a Rule 17 duty no paragraph confers — 8(f)(iii)'s content,
   and why `none` is explicit.
 - **Undetermined term.** "Exhibiting the signals in Rule 28" is a
-  display-compliance fact `18d1` does not read; the entry is wider (`Q-34`).
-- Entries: `18d1`, `8f3`.
+  display-compliance fact `rule:18d_i` does not read; the entry is wider (`Q-34`).
+- Entries: `rule:18d_i`, `rule:8f_iii`.
 
 ### INV-18f1 — the WIG craft keeps well clear
 
@@ -575,7 +577,7 @@ in flight near the surface, she holds `keep-clear` with respect to every other
 vessel — keeps well clear and avoids impeding their navigation — and the other
 holds `none`. `keep-clear` is outside the give-way/stand-on pairing and Rule 16.
 
-- Entries: `18f1`.
+- Entries: `rule:18f_i`.
 
 ---
 
@@ -601,9 +603,9 @@ not jointly exhaustive (`INV-19a-third-state`); Rule 19 supplements Section I
   cross it and back inside one encounter, and no paragraph says what becomes of
   a 13(d) latch or a Rule 17 phase: `Q-55`.
 - **Undetermined term.** "In or near an area of restricted visibility" has no
-  fact (3(l)'s atmospheric condition is nowhere in `data/facts.json`), so `19a`
+  fact (3(l)'s atmospheric condition is nowhere in `data/facts.json`), so `rule:19a`
   selects Section III for any pair not in sight — wider — and records a gap.
-- Entries: `11`, `19a`, complementary on `pair:geo:in_sight`.
+- Entries: `rule:11`, `rule:19a`, complementary on `pair:geo:in_sight`.
 
 ### INV-19a-noroles — Section III has no give-way and no stand-on vessel
 
@@ -633,7 +635,7 @@ excludes Section II, 19(a) excludes Rule 19, and only Section I governs.
 - **Why written down.** A hole forced by both scope paragraphs, which "not
   Section II, so Section III" will not have. The model closes it by dropping
   19(a)'s second conjunct — a decision, not a reading: `Q-56`.
-- Entries: `19a`'s `gap`.
+- Entries: `rule:19a`'s `gap`.
 
 ### INV-19b — safe speed, and engines ready