colregs 0.1.1 → 0.2.2

package/docs/budgets.json

@@ -0,0 +1,162 @@
+{
+  "$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,
+    "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/conventions.md

@@ -0,0 +1,27 @@
+# Conventions
+
+## Ink, pencil, open
+
+Design documents in this project mark each decision with a confidence
+level. The level is not a comment on the author's certainty; it is the
+**rule for who may change it and on what grounds.** A session reads the
+level before it reads the content, and behaves accordingly.
+
+| level | marker | who changes it | on what grounds |
+|---|---|---|---|
+| **Ink** | none (default in ADRs) | Mark | significant evidence: a counterexample, a verification result, a primary source. A session may argue, citing the evidence. It never edits ink itself. |
+| **Pencil** | `✎` | any session | a better idea. Log the change and why. Each pencilled item names what would settle it. |
+| **Open** | `?` | anyone proposes | a proposal moves it to pencil |
+
+How to ask a session about them:
+
+- "What's in pencil?" — list them, with what would settle each.
+- "Should we change this pencil item?" — give an opinion and change it if
+  Mark agrees, or on your own if the doc says the session may.
+- "Should we change this ink item?" — answer only with evidence. If there is
+  none, say "no evidence to reopen it" and stop.
+
+Ink and pencil are per item, not per document. A document is mostly ink
+with pencilled items, or mostly pencil with a few ink anchors; both are
+normal. Moving an item from pencil to ink is a decision Mark makes, and it
+gets a one-line log entry saying what settled it.

package/docs/gates.json

@@ -0,0 +1,84 @@
+{
+  "note": "Machine-readable mirror of the reversibility gates in docs/requirements.md \u00a710. Governance metadata about this repository, not COLREGS data \u2014 it deliberately lives in docs/ rather than data/, which is the consumer-facing model. REQ-GATE-3 is enforced against this file by test/data.test.mjs; the prose section is authoritative for the reasoning, this file is authoritative for status.",
+  "requirements": [
+    "REQ-GATE-1",
+    "REQ-GATE-2",
+    "REQ-GATE-3",
+    "REQ-GATE-4"
+  ],
+  "closing_events": {
+    "1.0-tag": "the 1.0 version tag \u2014 REQ-GATE-3 blocks it until every gate carrying this closing event has been re-taken",
+    "first-non-english-corpus": "the second corpus of any one jurisdiction, which in practice is the first non-English text",
+    "first-community-translation-of-national-corpus": "the first `community`-tier translation of a `national`-tier corpus",
+    "first-external-contribution": "the first merged contribution from someone other than the copyright holder",
+    "none": "the decline does not get cheaper or dearer with time; recorded so it is not re-read as merely deferred"
+  },
+  "statuses": {
+    "open": "declined for now, not re-taken; adoption still possible at the stated cost",
+    "re-taken": "reconsidered deliberately and confirmed as declined, in the cited ADR",
+    "adopted": "the declined design was subsequently adopted, in the cited ADR",
+    "declined-permanently": "declined on grounds that do not decay; no closing event exists"
+  },
+  "gates": [
+    {
+      "id": "GATE-1",
+      "title": "`paragraph_id` split from `citation_path`",
+      "declined_in": "docs/adr/0003-language-as-a-dimension.md",
+      "closing_event": "1.0-tag",
+      "trigger": "a paragraph path that keeps its spelling while changing what text it denotes, WITHIN ONE JURISDICTION ACROSS RELEASES. Two routes: an IMO amendment renumbering an `intl` path (verified real \u2014 A.910(22) displaced 23(c) to 23(d); A.464(XII) relettered 24(g) to 24(h)), or a national body renumbering its own amalgamation, so that e.g. `us/inland 24(c)` denotes different text in vN+1 than in vN. Cross-jurisdiction divergence at one point in time is NOT this trigger: the effective identifier is (jurisdiction, path), so the 15 same-path-different-text rows in the 33 CFR 83 diff are REQ-MODEL-1 working as designed.",
+      "status": "open",
+      "settled_by": null,
+      "note": "Open on timing, not outcome: if the trigger fires the split is forced and lands as a major version. Ruling 2026-08-30 (requirements.md \u00a710): does not flip on today's data \u2014 no published path has changed denotation \u2014 but leans adopt, decided in the second-jurisdiction bundle with GATE-2 and Q-10. That bundle is also where the re-check happens; it is justified by Q-11 and GATE-2, not by cross-jurisdiction divergence."
+    },
+    {
+      "id": "GATE-2",
+      "title": "instrument \u2192 edition \u2192 corpus as first-class layers",
+      "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."
+    },
+    {
+      "id": "GATE-3",
+      "title": "legal-status \u00d7 translation-status as two enums",
+      "declined_in": "docs/adr/0003-language-as-a-dimension.md",
+      "closing_event": "first-community-translation-of-national-corpus",
+      "trigger": "a real corpus whose legal tier and translation tier disagree in a way a consumer must filter on and cannot from the metadata as structured",
+      "status": "open",
+      "settled_by": null,
+      "note": "Half-adopted: one tier for legal authority (REQ-LANG-3), translation provenance as structured metadata (REQ-LANG-8, REQ-PROV-6)."
+    },
+    {
+      "id": "GATE-4",
+      "title": "a package-encoded language fallback chain",
+      "declined_in": "docs/adr/0003-language-as-a-dimension.md",
+      "closing_event": "none",
+      "trigger": null,
+      "status": "declined-permanently",
+      "settled_by": "docs/adr/0003-language-as-a-dimension.md",
+      "note": "The door opens outward: loosening REQ-LANG-7 later is additive, tightening it later would break consumers. Recorded so the asymmetry is not re-discovered as an argument for adopting early."
+    },
+    {
+      "id": "GATE-5",
+      "title": "a CI-enforced terminology glossary",
+      "declined_in": "docs/adr/0003-language-as-a-dimension.md",
+      "closing_event": "none",
+      "trigger": null,
+      "status": "declined-permanently",
+      "settled_by": "docs/adr/0003-language-as-a-dimension.md",
+      "note": "Declined for legal corpora \u2014 it follows from verbatimness (REQ-MODEL-1) and does not decay. For display catalogs it is contributor guidance, gated on contribution docs existing at all."
+    },
+    {
+      "id": "GATE-6",
+      "title": "the compilation's outbound licence",
+      "declined_in": "docs/adr/0004-licence-layering.md",
+      "closing_event": "first-external-contribution",
+      "trigger": "deciding the data side wants CC0 or CC BY 4.0 separately from the code (REQ-PROV-4, Q-9)",
+      "status": "open",
+      "settled_by": null,
+      "note": "ADR 0004 settles the code licence (MIT \u2192 Apache-2.0) and leaves the data licence open. Already-published npm versions stay under the licence they shipped with; the gate governs future releases only, and is held open deliberately by REQ-PROV-7's CONTRIBUTING.md terms (DCO-style certification plus a relicensing grant); a CLA-assistant bot is the upgrade path if contributors arrive."
+    }
+  ]
+}