colregs 0.2.0 → 0.2.3

package/README.md

@@ -24,10 +24,16 @@ fixtures/                fact records and the entries that apply to them
 
 ## Coverage
 
-Part C lights (Rules 20-31) only, `intl` jurisdiction only, night only. Day
-shapes, Part D signals, and every other jurisdiction (US Inland, Canada,
-CEVNI) are on the roadmap in [`docs/requirements.md`](docs/requirements.md)
-but not present here.
+Part C lights (Rules 20-31), `intl` jurisdiction, night only. Day shapes,
+Part D signals, and every other jurisdiction (US Inland, Canada, CEVNI) are
+on the roadmap in [`docs/requirements.md`](docs/requirements.md) but not
+present here.
+
+One exception, not a claim to model the Inland Rules: `us/inland` carries
+two entries, `30a-buoy` and `30b-buoy`, for a vessel made fast to a mooring
+buoy — 33 CFR 90.5 deems her at anchor and the Convention does not, so the
+case cannot be stated under `intl` at all
+([ADR 0008](docs/adr/0008-mooring-buoy-modifier.md)).
 
 ## The four layers
 
@@ -151,9 +157,9 @@ add to Rule 23 rather than replacing it. Relations between them:
 | `rel:includes` | import the referenced entry's **lights only**, never its predicate |
 | `rel:conditional_includes` | import lights when the stated `when` holds; `one_of` is a set of legal alternatives |
 | `rel:in_lieu_of` | this entry's lights replace the referenced entries' lights |
-| `rel:excludes` | must not be shown together (25(c) and the tricolor) |
+| `rel:excludes` | must not be shown together: a pick-one between alternatives (25(c) and the tricolor), never one obligation vetoing another |
 | `rel:exempts` | the referenced requirement does not apply (30(e)) |
-| `rel:overrides` | the superiority relation: this paragraph's requirement prevails over the referenced one's when both apply (Rule 18's "except where Rules 9, 10 and 13 otherwise require") |
+| `rel:overrides` | the superiority relation: this paragraph's requirement prevails over the referenced one's when both apply (Rule 18's "except where Rules 9, 10 and 13 otherwise require"); for lights, Rule 26(a)'s "only the lights prescribed in this Rule" displacing Rule 30's anchor lights |
 
 A condition on whether a paragraph applies to the vessel at all goes in the
 predicate; a condition on which of two applicable paragraphs prevails is a
@@ -341,7 +347,7 @@ came out right.
 From 0.2.0 on, every identifier in the package is immutable once published
 (REQ-MODEL-10). [`data/deprecated-identifiers.json`](data/deprecated-identifiers.json)
 is the REQ-MODEL-11 registry a retired identifier goes into, and `npm test`
-refuses a removal that is not recorded there.
+refuses a removal that is not recorded there. [`data/version.json`](data/version.json) mirrors `package.json`; release-please keeps it in sync (see [ADR 0009](docs/adr/0009-data-version-stamp.md)).
 
 ## Provenance and licence
 

package/data/applicability.json

@@ -410,8 +410,15 @@
      "count": 1
     }
    ],
-   "rel:includes": [
-    "23a34"
+   "rel:conditional_includes": [
+    {
+     "when": {
+      "fact:position": "position:underway"
+     },
+     "rel:includes": [
+      "23a34"
+     ]
+    }
    ],
    "modality": "shall",
    "images": [
@@ -427,10 +434,17 @@
     "fact:composite_unit": true
    },
    "lights": [],
-   "rel:includes": [
-    "23a1",
-    "23a2",
-    "23a34"
+   "rel:conditional_includes": [
+    {
+     "when": {
+      "fact:position": "position:underway"
+     },
+     "rel:includes": [
+      "23a1",
+      "23a2",
+      "23a34"
+     ]
+    }
    ],
    "modality": "shall",
    "images": [
@@ -453,8 +467,15 @@
      "arrangement": "vertical"
     }
    ],
-   "rel:includes": [
-    "23a34"
+   "rel:conditional_includes": [
+    {
+     "when": {
+      "fact:position": "position:underway"
+     },
+     "rel:includes": [
+      "23a34"
+     ]
+    }
    ],
    "rel:in_lieu_of": [
     "23a1",
@@ -640,7 +661,10 @@
    "jurisdiction": "intl",
    "cite": "26(b)(i)",
    "when": {
-    "fact:activity": "activity:trawling"
+    "fact:activity": "activity:trawling",
+    "fact:position": {
+     "not": "position:aground"
+    }
    },
    "lights": [
     {
@@ -656,7 +680,7 @@
      "position": "lower"
     }
    ],
-   "rel:excludes": [
+   "rel:overrides": [
     "30a",
     "30b"
    ],
@@ -664,14 +688,17 @@
    "images": [
     "NRHB_26_b.png"
    ],
-   "notes": "Rule 26(a): a vessel engaged in fishing shall exhibit only the lights of Rule 26, whether underway or at anchor — hence the exclusion of Rule 30."
+   "notes": "Rule 26(a) — 'only the lights prescribed in this Rule' — prevails over Rule 30's anchor lights underway or at anchor (rel:overrides, ADR 0007). Aground is neither (Rule 3(i)); she shows 30(d) alone."
   },
   {
    "id": "26b-mast",
    "jurisdiction": "intl",
    "cite": "26(b)(ii)",
    "when": {
-    "fact:activity": "activity:trawling"
+    "fact:activity": "activity:trawling",
+    "fact:position": {
+     "not": "position:aground"
+    }
    },
    "lights": [
     {
@@ -722,7 +749,10 @@
    "jurisdiction": "intl",
    "cite": "26(c)(i)",
    "when": {
-    "fact:activity": "activity:fishing"
+    "fact:activity": "activity:fishing",
+    "fact:position": {
+     "not": "position:aground"
+    }
    },
    "lights": [
     {
@@ -738,7 +768,7 @@
      "position": "lower"
     }
    ],
-   "rel:excludes": [
+   "rel:overrides": [
     "30a",
     "30b"
    ],
@@ -750,6 +780,9 @@
    "cite": "26(c)(ii)",
    "when": {
     "fact:activity": "activity:fishing",
+    "fact:position": {
+     "not": "position:aground"
+    },
     "fact:gear_extent_m": {
      "gt": 150
     }
@@ -1940,7 +1973,7 @@
    "effect": {
     "encounter": "overtaking"
    },
-   "note": "The latch, and the reason `hist` is a fact class rather than a note. Once either vessel has been the overtaking vessel the encounter stays an overtaking whatever the bearing does next, so this entry reads history alone and no geometry at all. It is the counterpart of the `hist:was_overtaking: false` gate on 14b and 15a-crossing: without both halves the drawn-out bearing would produce a head-on or a crossing beside the overtaking, which is exactly the reclassification 13(d) forbids.",
+   "note": "The latch, and the reason `hist` is a fact class rather than a note. Once either vessel has been the overtaking vessel the encounter stays an overtaking whatever the bearing does next, so this entry reads history alone and no geometry at all. It is the counterpart of the `hist:was_overtaking: false` gate on 14b and 15a-crossing: without both halves the drawn-out bearing would produce a head-on or a crossing beside the overtaking, which is exactly the reclassification 13(d) forbids. `pair:geo:in_sight` stays in the gate; a Rule 19(d)(i) entry reads `hist:was_overtaking` directly (Q-49).",
    "gap": "'Until she is finally past and clear' is the paragraph's own end condition and nothing in the fact vocabulary carries it, so in this model the latch never clears. A consumer sets and clears `hist:was_overtaking` itself. Recorded rather than approximated with a range or a bearing: past and clear is a seamanship judgement, and inventing a threshold for it would be the kind of number Q-40's neighbours are about. Q-47."
   },
   {
@@ -2114,6 +2147,56 @@
    },
    "note": "The role half of 15(a): the vessel which has the other on her own starboard side keeps out of the way. Own's bearing constraint is the starboard half of the non-overtaking sector, and its upper edge is the same declared constant 13b reads, so it is not a hand-listed sector either; the partition test asserts that this entry selects exactly the crossings in which the other bears between 0 and 180 relative, which is what makes the shorthand checkable rather than trusted. 'Two power-driven vessels' is 3(b) and nothing more, so both subjects are gated on `fact:propulsion: propulsion:power` and on no Rule 18 rank (Q-40): a vessel engaged in fishing, not under command, restricted in her ability to manoeuvre or constrained by her draught is a power-driven vessel whenever her machinery is in use, and is inside Rule 15. Where Rule 18 also ranks the pair, that entry carries `rel:overrides` against this one -- 18(a)(i)-(iii) from the unranked vessel's side, 18(c)(i)-(ii) from the fishing vessel's, 18(f)(i) from the WIG craft's -- because Rule 18's opening words except Rules 9, 10 and 13 and no others; 13(a)'s 'notwithstanding' would override it the same way, and does not need to, because this entry's bearing gates and its `hist:was_overtaking: false` already exclude every overtaking. Where Rule 18 leaves the pair unordered -- two vessels engaged in fishing, or one not under command and one restricted in her ability to manoeuvre -- this entry is the only norm in force, and it lays a helm duty on a vessel that may be unable to discharge it; that is Rule 2's region and is recorded in Q-40 rather than gated away.",
    "gap": "15(a)'s second duty -- 'shall, if the circumstances of the case admit, avoid crossing ahead of the other vessel' -- is `conduct` with a practicability caveat, and neither half fits a precedence entry. It is dropped here, which is Q-31's shape again: the caveat has no field to move into unless the duty happens to be a role, and this one is an action."
+  },
+  {
+   "id": "30a-buoy",
+   "jurisdiction": "us/inland",
+   "cite": "30(a)",
+   "when": {
+    "fact:position": "position:moored",
+    "fact:on_mooring_buoy": true
+   },
+   "lights": [
+    {
+     "light": "light:all_round",
+     "color": "white",
+     "count": 1,
+     "position": "in the fore part"
+    },
+    {
+     "light": "light:all_round",
+     "color": "white",
+     "count": 1,
+     "position": "at or near the stern, at a lower level than the fore one"
+    }
+   ],
+   "modality": "shall",
+   "note": "33 CFR 90.5 deems a vessel made fast to a mooring buoy to be a vessel at anchor, so Inland Rule 30(a) reaches her. The Convention has no such deeming provision: under intl she is 'moored' by Rule 3(i) and no paragraph prescribes lights for her."
+  },
+  {
+   "id": "30b-buoy",
+   "jurisdiction": "us/inland",
+   "cite": "30(b)",
+   "when": {
+    "fact:position": "position:moored",
+    "fact:on_mooring_buoy": true,
+    "fact:length_m": {
+     "lt": 50
+    }
+   },
+   "lights": [
+    {
+     "light": "light:all_round",
+     "color": "white",
+     "count": 1,
+     "position": "where it can best be seen"
+    }
+   ],
+   "rel:in_lieu_of": [
+    "30a-buoy"
+   ],
+   "modality": "may",
+   "note": "The under-50 m alternative, on the same 33 CFR 90.5 deeming that brings 30a-buoy in. It is a separate entry because widening 30b's predicate would edit an intl entry to carry a national delta, which REQ-SCOPE-4 forbids."
   }
  ]
 }

package/data/facts.json

@@ -65,6 +65,12 @@
    "refines": "fact:position=position:underway",
    "note": "Undefined in the Rules; it means moving through the water. Underway but not making way is free drifting. Only the 26/27-family predicates read it (26(b)(iii), 26(c)(iii), 27(a)(iii), 27(b)(iii)); Rules 23 and 25 gate on 'underway' alone, so a power-driven vessel drifting in neutral still shows full running lights.",
    "actuable": true
+  },
+  "fact:on_mooring_buoy": {
+   "type": "boolean",
+   "refines": "fact:position=position:moored",
+   "note": "Made fast to a mooring buoy rather than to the shore. Rule 3(i) makes both 'moored', and the Convention prescribes no lights for either. Only a jurisdiction that deems a buoy-moored vessel to be at anchor reads it -- US Inland, 33 CFR 90.5 -- so under intl it selects nothing.",
+   "actuable": true
   }
  },
  "numerics": {
@@ -291,12 +297,13 @@
   }
  },
  "actuable_subset": {
-  "note": "What a switching consumer needs and can get: the three axes (decodable from navigation.state), making_way, and length_m. Everything else is education-side.",
+  "note": "What a switching consumer needs: the three axes (decodable from navigation.state), making_way, on_mooring_buoy, and length_m. Decodability is not the test -- making_way and on_mooring_buoy change which lights must burn and the helm knows both, so a consumer must ask. Everything else is education-side.",
   "fields": [
    "fact:propulsion",
    "fact:activity",
    "fact:position",
    "fact:making_way",
+   "fact:on_mooring_buoy",
    "fact:length_m"
   ]
  },
@@ -419,6 +426,11 @@
    "not defined (example)"
   ],
   "lossy": [
+   {
+    "what": "made fast to a mooring buoy vs. made fast to the shore",
+    "why": "'moored' covers both and no SignalK path distinguishes them, so fact:on_mooring_buoy cannot be derived from navigation.state and must be asked of the consumer. Under us/inland it decides whether the 30(a)/(b) anchor lights are required.",
+    "cite": "3(i)"
+   },
    {
     "what": "fishing or trawling at anchor",
     "why": "Rule 26(a) applies 'whether underway or at anchor', but 'fishing' and 'anchored' are mutually exclusive values of one flat enum, so the pair cannot be stated.",

package/data/version.json

@@ -0,0 +1,3 @@
+{
+  "version": "0.2.3"
+}

package/docs/adr/0007-rule26-overrides-and-aground.md

@@ -0,0 +1,68 @@
+# ADR 0007 — Rule 26 overrides Rule 30, and neither reaches a vessel aground
+
+Date: 2026-09-08
+Status: accepted
+
+## Context
+
+colregs-engine's conformance register recorded two findings against this
+package's data. FIND-01/02: `26b-id` and `26c-id` are `shall`, carry
+`rel:excludes: ["30a","30b"]`, and `30a` is `shall` too — two obligations
+excluding each other. `rel:excludes` (REQ-MODEL-7) is symmetric and
+untimed: it says two things must not be shown together, the way 25(c) and
+the tricolor are alternatives under 25(b), never that one obligation
+displaces another. Rule 26(a) is directional — "a vessel engaged in fishing
+... shall exhibit only the lights prescribed in this Rule" — one paragraph
+stating what prevails, not a mutual veto. REQ-MODEL-13 and ADR 0005 §4
+already drew this line for Rule 18 over Rules 12 and 15; Rule 26 over Rule
+30 is the same shape and had not yet been moved.
+
+colregs-engine#32 found the consequence: a fishing vessel aground evaluated
+to `26c-id`'s red-over-white plus `30d-red`'s two reds and no anchor light
+at all, because `26c-id` carried no position gate — it applied whether the
+vessel was underway, anchored or aground — and its exclusion of `30a`/`30b`
+stripped the anchor lights `30d-anchor` imports from them, leaving nothing
+in their place. Rule 26(a)'s own words are "whether underway or at anchor";
+aground is neither state (Rule 3(i) defines "underway" as not made fast to
+the shore, at anchor, or aground). Rule 26 has no jurisdiction over a vessel
+aground; Rule 30(d) alone does.
+
+## Decision
+
+1. **`rel:excludes` is pick-one between alternatives; two obligations never
+   exclude each other.** Where two `shall` entries were related by
+   `rel:excludes`, that was always a superiority relation misfiled — REQ-
+   MODEL-7's mutual-exclusion semantics never fit two unconditional duties.
+
+2. **`rel:overrides` carries Rule 26(a).** `26b-id` and `26c-id` now carry
+   `rel:overrides: ["30a","30b"]` in place of `rel:excludes`. On a `display`
+   entry, "prevails" means: while the overriding entry applies, the
+   overridden entry's lights are not shown, even though its own predicate
+   is satisfied. A consumer resolving `rel:overrides` (as colregs-engine
+   does) drops `30a`/`30b`'s lights whenever `26b-id`/`26c-id` fires; a
+   consumer that does not resolve it sees both, which is `rel:excludes`'
+   old, wrong behaviour restored — the reason to resolve it.
+
+3. **Aground is neither underway nor at anchor, so a vessel aground shows
+   Rule 30(d) alone.** `26b-id`, `26b-mast`, `26c-id` and `26c-gear` — the
+   four Rule 26 lights entries with no position gate — now read
+   `"fact:position": {"not": "position:aground"}`. `26b-mw`/`26c-mw` needed
+   no change: they already read `fact:making_way`, which refines underway
+   and is never true aground. Gating all four, not only the two FIND-01/02
+   named, is what "Rule 30(d) alone, full stop" requires: leaving the mast
+   or gear light ungated would still show a Rule 26 light beside 30(d)'s.
+
+## Consequences
+
+- A consumer must resolve `rel:overrides` on `display` entries to get the
+  right light set at anchor; colregs-engine already does, in a PR landing
+  alongside this one, and will bump its `colregs` pin once this releases.
+- `fact:position` is now a required read for Rule 26's lights entries. A
+  predicate never fires on an absent fact (`satisfies`, `test/data.test.mjs`),
+  so a fact record that omits `fact:position` no longer shows any Rule 26
+  light — same rule as `not` elsewhere in this package, applied for the
+  first time to a Rule 26 entry.
+- Trawling while anchored remains a pair the data cannot rule out at the
+  facts level — `fact:activity` and `fact:position` are orthogonal axes —
+  pending its own declaration; this ADR does not add one.
+- colregs-engine's FIND-01 and FIND-02 close on this ADR.

package/docs/adr/0008-mooring-buoy-modifier.md

@@ -0,0 +1,87 @@
+# ADR 0008 — `position:moored` stays one value; a mooring buoy is a modifier
+
+Date: 2026-09-08
+Status: accepted
+
+## Context
+
+Rule 3(i) defines "underway" as "not at anchor, or made fast to the shore,
+or aground". A vessel made fast to a mooring buoy is none of those three:
+she is not at anchor, and a buoy is not the shore. Read strictly she is
+therefore *underway*, and would owe Rule 23 or Rule 25 running lights while
+lying still on a buoy all night — which nobody does and no authority
+expects. Read the way every pilot book reads it, she is moored, and the
+Convention prescribes her no lights at all: no paragraph of Part C reaches
+`position:moored`.
+
+The United States closed the gap by legislation, not by interpretation.
+33 CFR 90.5 provides that a vessel made fast to a mooring buoy is deemed to
+be a vessel at anchor, which brings Inland Rule 30(a) — and for a vessel
+under 50 m, 30(b) — to bear on her. That is a national deeming provision.
+It has no counterpart in the Convention.
+
+The modelling question was whether "moored to a buoy" is a fourth value of
+`fact:position`, beside `position:moored`. It is not. Splitting the axis
+would make every existing predicate that reads `position:moored` silently
+wrong for the buoy case, and would encode a US rule in the shape of the
+international vocabulary — every consumer, in every jurisdiction, paying
+for a distinction only one jurisdiction draws.
+
+## Decision
+
+1. **`position:moored` stays one value.** The axis is not split, and no
+   existing identifier is renamed.
+
+2. **`fact:on_mooring_buoy` is a boolean modifier refining
+   `fact:position=position:moored`,** shaped exactly like `fact:making_way`
+   refines `position:underway`. A modifier is the established way this
+   package says "one state, two legally distinct sub-cases": the axis value
+   stays the coarse fact everyone agrees on, and the modifier carries the
+   refinement only the rules that need it read.
+
+3. **Alongside prescribes no lights, and that is the Convention's answer,
+   not a gap.** Rule 3(i)'s "made fast to the shore" is a moored vessel; no
+   Part C paragraph gives her lights. A fixture asserts the empty set, so
+   the silence is tested rather than assumed.
+
+4. **The buoy case gets the 30(a)/30(b) anchor lights only under a
+   jurisdiction that says so.** Two entries, `30a-buoy` and `30b-buoy`,
+   carry `jurisdiction: us/inland` and cite 30(a) and 30(b); `30b-buoy` is
+   `may`, `rel:in_lieu_of` `30a-buoy`, on the same under-50 m gate 30(b)
+   uses. Under `intl` the same fact record selects nothing. This is the
+   jurisdiction dimension of ADR 0001 doing the job it was built for: a
+   national departure is a delta on the base, never an edit to it.
+
+5. **The fixture corpus gains a per-case `jurisdiction`.** The corpus-level
+   value is now the default; a case may name its own and is evaluated
+   against `intl` plus that jurisdiction's deltas (REQ-SCOPE-3). Without it
+   the evaluator has no way to say which body of rules a fact record is
+   being read under, and a national entry would leak into every
+   international answer.
+
+6. **`fact:on_mooring_buoy` is actuable and is not derivable from SignalK.**
+   `navigation.state: "moored"` covers alongside and buoy alike and no
+   SignalK path separates them, so the fact is recorded in the decode
+   table's `lossy` list and must be asked of the consumer. SignalK is an
+   integration point, not a constraint on the model: a fact the rules turn
+   on stays in the vocabulary whether or not a sensor can report it.
+
+## Consequences
+
+- This is the first non-`intl` applicability entry in the package, and it
+  arrives before Part C is complete for `intl` (REQ-PART-1) and before the
+  explicit suppression mechanism REQ-SCOPE-3 requires. Both are amended
+  with a narrow carve-out: a delta that only *adds* entries suppresses
+  nothing, so silence-means-inherit — the hazard Q-11 records, where a
+  jurisdiction deliberately has no rule and inherits one anyway — cannot
+  arise from it. A delta that suppresses or replaces an `intl` entry still
+  waits on that mechanism.
+- The evaluator in `test/data.test.mjs` now filters by jurisdiction in both
+  directions, forward and drift. An entry from another jurisdiction is not
+  a drift candidate: it was never in force for that record.
+- A consumer that ignores jurisdiction will show anchor lights to a
+  buoy-moored vessel in the English Channel. The filter is three lines and
+  the fixtures pin both answers.
+- `us/inland` is now a jurisdiction with exactly two entries in it. It is
+  not a claim to model the Inland Rules; README's coverage statement
+  (REQ-SCOPE-6) says so explicitly.

package/docs/adr/0009-data-version-stamp.md

@@ -0,0 +1,47 @@
+# ADR 0009 — `data/version.json` is the single version stamp for `data/`
+
+Date: 2026-09-08
+Status: accepted
+
+## Context
+
+Nothing in this package's schema or data files carries a version anywhere a
+consumer can check it against. colregs-engine's `Evaluation.colregs.version`
+names the engine's own resolved npm dependency, not the `data` object it was
+actually handed — so a caller evaluating against a stale cached fixture, a
+monorepo with mismatched `colregs` versions, or applicability data
+reconstructed by hand from an old export gets a result silently attributed
+to whatever release happens to be resolved locally: not a crash, not a
+warning, just a wrong-but-plausible `Evaluation`.
+
+Two alternatives were considered and rejected:
+
+- **A `version`/`dataVersion` field on each of the seven `data/*.json`
+  files.** The files already release as one unit — one npm version, one
+  `package.json` — so seven independent copies can only drift, never add
+  information.
+- **Leaning on the npm package version alone (status quo).** That is
+  exactly what colregs-engine already does, and exactly what it cannot
+  verify against, because the installed package version and the data
+  actually passed into `evaluate()` are two different things once the data
+  crosses a process/cache/file boundary.
+
+## Decision
+
+A single manifest, `data/version.json`, is the one source of truth:
+
+- `{"version": "<semver>"}`, matching `package.json` at release time.
+- `schema/version.schema.json` validates it, same pattern as every other
+  `data/*.json` file.
+- `release-please-config.json`'s `extra-files` generic JSON updater keeps
+  it in sync on every release, the same way `.release-please-manifest.json`
+  already is — the version cannot go stale without the release itself
+  failing.
+
+## Consequences
+
+- colregs-engine (or any consumer) can compare its resolved package version
+  against `data/version.json` at the point `evaluate()` receives `data`,
+  and throw or warn on a mismatch instead of silently reporting the wrong
+  version. That comparison is a colregs-engine change, tracked separately.
+- `data/version.json` is never hand-edited; release-please owns it.

package/docs/budgets.json

@@ -0,0 +1,163 @@
+{
+  "$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,
+    "AGENTS.md": 120,
+    "CLAUDE.md": 10,
+    "docs/requirements.md": 1500,
+    "docs/identifiers.md": 450,
+    "docs/part-b-invariants.md": 950,
+    "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,
+    "required": true,
+    "pending": []
+  },
+  "json_prose": {
+    "targets": [
+      "data/*.json",
+      "fixtures/*.json"
+    ],
+    "keys": [
+      "note",
+      "gap",
+      "narrative",
+      "settled_by",
+      "rationale",
+      "why"
+    ],
+    "max_chars": 450,
+    "grandfathered": [
+      "data/applicability.json#/effects/note",
+      "data/applicability.json#/known_omissions/9/why",
+      "data/applicability.json#/known_omissions/10/why",
+      "data/applicability.json#/known_omissions/11/why",
+      "data/applicability.json#/entries/43/note",
+      "data/applicability.json#/entries/44/note",
+      "data/applicability.json#/entries/45/note",
+      "data/applicability.json#/entries/47/note",
+      "data/applicability.json#/entries/50/note",
+      "data/applicability.json#/entries/51/note",
+      "data/applicability.json#/entries/52/note",
+      "data/applicability.json#/entries/53/note",
+      "data/applicability.json#/entries/55/note",
+      "data/applicability.json#/entries/56/note",
+      "data/applicability.json#/entries/60/note",
+      "data/applicability.json#/entries/61/note",
+      "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",
+      "data/facts.json#/derived/fact:rule18_class/decode/2/note",
+      "data/facts.json#/situation/kinematics/kin:wind_side/note",
+      "data/facts.json#/situation/geometry/directional/geo:rel_bearing_deg/note",
+      "data/facts.json#/situation/geometry/consistency/note",
+      "data/facts.json#/situation/history/hist:was_overtaking/note",
+      "data/facts.json#/situation/constants/note",
+      "fixtures/situation-fixtures.json#/case_status/note",
+      "fixtures/situation-fixtures.json#/cases/0/narrative",
+      "fixtures/situation-fixtures.json#/cases/1/narrative",
+      "fixtures/situation-fixtures.json#/cases/2/narrative",
+      "fixtures/situation-fixtures.json#/cases/46/narrative",
+      "fixtures/situation-fixtures.json#/cases/63/narrative",
+      "fixtures/situation-fixtures.json#/cases/76/narrative",
+      "fixtures/situation-fixtures.json#/cases/77/narrative",
+      "fixtures/situation-fixtures.json#/cases/78/narrative",
+      "fixtures/situation-fixtures.json#/cases/79/narrative"
+    ]
+  },
+  "narration": {
+    "targets": [
+      "README.md",
+      "AGENTS.md",
+      "CLAUDE.md",
+      "data/*.json",
+      "fixtures/*.json",
+      "test/*.mjs",
+      "docs/**/*.md"
+    ],
+    "scope": {
+      "pr": [
+        "README.md",
+        "AGENTS.md",
+        "CLAUDE.md",
+        "data/*.json",
+        "fixtures/*.json",
+        "test/*.mjs"
+      ],
+      "issue": [
+        "README.md",
+        "AGENTS.md",
+        "CLAUDE.md",
+        "data/*.json",
+        "fixtures/*.json",
+        "test/*.mjs"
+      ],
+      "phase": [
+        "README.md",
+        "AGENTS.md",
+        "CLAUDE.md",
+        "data/*.json",
+        "fixtures/*.json",
+        "test/*.mjs"
+      ],
+      "split": [
+        "README.md",
+        "AGENTS.md",
+        "CLAUDE.md",
+        "data/*.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",
+        "match": "the session"
+      },
+      {
+        "file": "docs/requirements.md",
+        "hash": "cdbdaf145c0a",
+        "match": "seeded 2026-"
+      }
+    ]
+  },
+  "voice": {
+    "scope": "tree",
+    "targets": [
+      "README.md",
+      "AGENTS.md",
+      "CLAUDE.md",
+      "docs/**/*.md",
+      "data/*.json",
+      "fixtures/*.json"
+    ]
+  },
+  "unique_ids": [
+    {
+      "file": "docs/requirements.md",
+      "pattern": "\\*\\*(Q-\\d+|REQ-[A-Z]+-\\d+)\\*\\*"
+    }
+  ]
+}

package/docs/identifiers.md

@@ -36,7 +36,7 @@ resolves that collision by construction rather than by convention.
 | form | class | examples |
 |---|---|---|
 | `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:<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` |
 | `rel:<name>` | the five relation verbs (`data/applicability.json`) | `rel:includes`, `rel:in_lieu_of`, `rel:exempts` |