edoxen 0.3.1 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a87eaf24182b1fd7400efbd2af10681f4059a35cd57c807759a8015a59a1c0f1
-  data.tar.gz: 53ede8ad87d1a25bbf766d7196e6437a8455f431af313ba5b9752cbd42d17050
+  metadata.gz: 69a86986a86602665699b5598622d32a63658c302737587f68b7a9b095a471e1
+  data.tar.gz: 1201e014ac06c2e4accb00dfd00660f577f6f6464f5d7990553714b796af8314
 SHA512:
-  metadata.gz: a14ac6664ffa8ec1f1fcd31ace23257a740dcad3fab41ead54d542440a53618ac8ad46bb495afeb44c62db7b850d35d789ee7a888245f4e6b3ac0afe092310ee
-  data.tar.gz: 991a18091cb7ec21ddfe70b2691244b3e8a6ba869135545f6249ffa35d56439afbf578a867d56bdce6c3555f177c59f43c73f8c27abb119527af36c42e6b17fd
+  metadata.gz: 7ec73b629af4dd2997fea614665347177f273569349d0221e414f9dc9b2dbb8f083b3d964675286bb9a76d449a5a4c7c2cf2981db028ebf5f0d2e54249abb77d
+  data.tar.gz: 52534618f6468c4da8effd9bcb23e978487e1857da1a9832fa8d1ed665e72324a13397657b0cb8f6c828be4ef45e9d669781a208b7135c09e97a1b833cc6c69e

data/CLAUDE.md

@@ -4,15 +4,19 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this gem is
 
-`edoxen` is an information model for formal resolutions and decisions
-(ISO/TC 154, CIPM, OIML, etc.). It provides:
+`edoxen` is an information model for formal proceedings — meetings,
+agendas, minutes, attendance, votes, and the resolutions adopted by
+standards bodies (ISO/TC 154, CIPM, OIML, etc.). It provides:
 
 - A set of `Lutaml::Model::Serializable` subclasses that mirror the canonical
   LutaML UML model in `../edoxen-model/models/*.lutaml`.
-- A JSON-Schema (`schema/edoxen.yaml`) used to validate real-world YAML
-  files via `SchemaValidator` (`json_schemer`).
-- A Thor CLI (`edoxen validate`, `edoxen normalize`) that wraps both the
-  schema validator and the Ruby model parser.
+- Two JSON-Schemas — `schema/edoxen.yaml` for `ResolutionCollection`
+  and `schema/meeting.yaml` for `Meeting` / `MeetingCollection` — used
+  to validate real-world YAML files via `SchemaValidator`
+  (`json_schemer`).
+- A Thor CLI that wraps both schemas and both model parsers:
+  `edoxen validate` / `edoxen normalize` for resolutions;
+  `edoxen validate-meetings` / `edoxen normalize-meetings` for meetings.
 
 ## Architecture
 

data/Gemfile

@@ -5,6 +5,10 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in edoxen.gemspec
 gemspec
 
+# Pre-release sources. Move to RubyGems once published; the gemspec
+# dep stays as `add_dependency "unlocode", "~> 0.1"` either way.
+gem "unlocodes", github: "metanorma/unlocode"
+
 gem "rake"
 gem "rspec"
 gem "rubocop"

data/README.adoc

@@ -1,26 +1,30 @@
 = Edoxen
 
-https://github.com/metanorma/edoxen[image:https://img.shields.io/github/stars/metanorma/edoxen.svg?style=social[GitHub Stars]]
-image:https://img.shields.io/github/license/metanorma/edoxen.svg[License]
-image:https://img.shields.io/github/actions/workflow/status/metanorma/edoxen/test.yml?branch=main[Build Status]
+https://github.com/edoxen/edoxen[image:https://img.shields.io/github/stars/edoxen/edoxen.svg?style=social[GitHub Stars]]
+image:https://img.shields.io/github/license/edoxen/edoxen.svg[License]
+image:https://img.shields.io/github/actions/workflow/status/edoxen/edoxen/test.yml?branch=main[Build Status]
 image:https://img.shields.io/gem/v/edoxen.svg[RubyGems Version]
 
 == Purpose
 
 Edoxen is a Ruby library for the canonical Edoxen information model of
-formal resolutions and decisions. It is built on top of the
+formal proceedings — meetings, agendas, minutes, attendance, votes,
+and the resolutions adopted by standards bodies and governance
+organisations. It is built on top of the
 https://github.com/lutaml/lutaml[ lutaml-model] serialization framework.
 
 The information model is defined in
-https://github.com/metanorma/edoxen-model/tree/main/models[ LutaML UML
+https://github.com/edoxen/edoxen-model/tree/main/models[ LutaML UML
 files] (one `.lutaml` per concept). This gem mirrors that model exactly —
 attribute declarations, enum values, and field shapes — so that anything
 you can express in LutaML you can also construct, serialize, and validate
 in Ruby.
 
 The intended users are standards organizations and governance bodies that
-need to publish structured records of formal decision-making. Real-world
-samples (ISO/TC 154, CIPM, OIML CIML) ship in `spec/fixtures/`.
+need to publish structured records of formal proceedings — the full
+lifecycle from draft agenda through adopted resolution, in any ISO 639-3
+language. Real-world samples (ISO/TC 154, CIPM, OIML CIML) ship in
+`spec/fixtures/`.
 
 == Installation
 
@@ -41,16 +45,23 @@ yaml = File.read('resolutions.yaml')
 collection = Edoxen::ResolutionCollection.from_yaml(yaml)
 
 collection.resolutions.each do |resolution|
-  prefix = resolution.identifier.first.prefix
-  number = resolution.identifier.first.number
-  puts "#{prefix}/#{number}"
-
-  resolution.localizations.each do |loc|
-    puts "  [#{loc.language_code}/#{loc.script}] #{loc.title}"
-    loc.actions.each do |action|
-      puts "    - #{action.type}: #{action.message}"
-    end
+  # identifier is StructuredIdentifier[1..*] — a Resolution can carry
+  # its TC number, SC number, and any cross-cutting reference number.
+  id = resolution.identifier.first
+  puts "#{id.prefix}/#{id.number}"
+
+  # Canonical rendering — English when available, else the first
+  # declared localization. See "Lookup accessors" below.
+  loc = resolution.primary_localization
+  puts "  [#{loc.language_code}/#{loc.script}] #{loc.title}"
+
+  loc.actions.each do |action|
+    puts "    - #{action.type}: #{action.message}"
   end
+
+  # Or look up a specific language explicitly:
+  fra = resolution.in_language("fra")
+  puts "  FR: #{fra.title}" if fra
 end
 
 # Round-trip back to YAML
@@ -95,6 +106,25 @@ Every translatable field on a Resolution is wrapped inside one of its
 (`identifier`, `doi`, `urn`, `agenda_item`, `dates`, `categories`,
 `meeting`, `relations`, `urls`) live on the parent `Resolution`.
 
+=== Lookup accessors
+
+Direct iteration over `localizations[]` is discouraged — the
+language-preference policy lives behind two accessors:
+
+* `Resolution#in_language(code, fallback: false)` — exact match by
+  ISO 639-3 code, or `nil` (or the first declared localization when
+  `fallback: true`).
+* `Resolution#primary_localization` — English when available, else
+  the first declared localization. Mirrors the glossarist
+  LocalizedConcept "preferred language" notion.
+
+[source,ruby]
+----
+resolution.in_language("fra")           # => Localization or nil
+resolution.in_language("deu", fallback: true)
+resolution.primary_localization         # English-or-first
+----
+
 == Multilingual resolution sets
 
 [source,yaml]
@@ -137,9 +167,10 @@ resolutions:
 
 == Command-line interface
 
-The `edoxen` executable exposes two commands.
+The `edoxen` executable exposes four commands — two for Resolution
+collections, two for Meeting/Agenda documents.
 
-=== `validate` — JSON-Schema validation + model parsing
+=== `validate` — JSON-Schema validation + model parsing for Resolutions
 
 [source,sh]
 ----
@@ -153,7 +184,7 @@ problems the schema can't express.
 
 Exit code is non-zero if any file fails.
 
-=== `normalize` — round-trip every fixture through the model
+=== `normalize` — round-trip Resolution YAML through the model
 
 [source,sh]
 ----
@@ -162,28 +193,134 @@ $ edoxen normalize legacy.yaml --inplace
 ----
 
 Loads each YAML file, parses it through the Ruby model, and writes the
-result back. Used to migrate between model versions. Either `--output DIR`
-or `--inplace` is required (mutually exclusive).
+result back. Either `--output DIR` or `--inplace` is required (mutually
+exclusive).
+
+=== `validate-meetings` — validate Meeting/Agenda YAML
+
+[source,sh]
+----
+$ edoxen validate-meetings "spec/fixtures/meetings/*.yaml"
+----
+
+Validates against `schema/meeting.yaml` and parses through
+`Edoxen::Meeting` (single-Meeting files) or `Edoxen::MeetingCollection`
+(wrappers). The schema's root is `oneOf` — both shapes are accepted.
+
+=== `normalize-meetings` — round-trip Meeting YAML through the model
+
+[source,sh]
+----
+$ edoxen normalize-meetings "spec/fixtures/meetings/*.yaml" --output clean/
+----
+
+Same shape as `normalize`, but for Meeting/Agenda documents.
+
+== Meeting & Agenda model
+
+The Meeting model represents the *event* that produces Resolutions,
+plus the agenda document that orders its business. Mirrors
+`edoxen-model/models/meeting*.lutaml`.
+
+[source]
+----
+MeetingCollection
+├── metadata:  MeetingCollectionMetadata
+└── meetings: Meeting[]
+              ├── identifier: StructuredIdentifier[1..*]
+              ├── urn, ordinal, type (MeetingType), status (MeetingStatus), year
+              ├── date_range: DateRange {start, end}
+              ├── committee, committee_group
+              ├── venues: Location[]   (multi-venue supported)
+              ├── general_area, city (UN/LOCODE, e.g. FRPAR), country_code (ISO 3166-1), virtual
+              ├── chair, secretary: Person
+              ├── host, hosts: HostRef[]   (typed: national_body/liaison/associate/organizer)
+              ├── source_urls: SourceUrl[]   (with `kind` discriminator)
+              ├── landing_url, registration_url
+              ├── agenda: Agenda
+              │            ├── identifier, status (AgendaStatus), source_doc
+              │            ├── items: AgendaItem[]
+              │            │            ├── label, kind (numbered/unnumbered/header/opening/closing)
+              │            │            ├── title, description
+              │            │            ├── references: Reference[]
+              │            │            ├── outcome (discussed/resolved/deferred/adopted/withdrawn)
+              │            │            └── resolution_ref (URN link to a Resolution)
+              │            └── opening_session, closing_session: ScheduleItem
+              ├── schedule: ScheduleItem[]   (the time-bound timetable)
+              ├── deadlines: Deadline[]
+              ├── localizations: MeetingLocalization[]   (per-language content)
+              ├── relations: MeetingRelation[]   (continues_from, joint_with, ...)
+              └── resolution_refs: String[]   (URN links to ResolutionCollections)
+----
+
+=== Linking Meetings to ResolutionCollections
+
+Meetings and ResolutionCollections are separate documents joined by URN:
+
+- `Meeting.resolution_refs: [urn:...]`
+- `ResolutionCollection.metadata.meeting_urn: urn:...`
+
+The join is by URN because the two have different lifetimes — agendas
+exist weeks before a meeting, resolutions only after adoption.
+
+=== Lookup accessors (parallel to the Resolution side)
+
+[source,ruby]
+----
+meeting = Edoxen::Meeting.from_yaml(File.read('meeting.yaml'))
+
+meeting.in_language("fra")                  # => MeetingLocalization or nil
+meeting.in_language("deu", fallback: true)  # falls back to first
+meeting.primary_localization                # English-or-first
+meeting.find_agenda_item("5.2")             # AgendaItem by label
+
+collection = Edoxen::MeetingCollection.from_yaml(...)
+collection.find_by_urn("urn:oiml:ciml:meeting:ciml-56")
+collection.find_by_identifier(prefix: "CIML", number: "56")
+----
 
 == Architecture
 
 * `lib/edoxen.rb` is the single entry-point. It configures
   `Lutaml::Model::Config` and `autoload`s every model class and service.
-* Each model lives in its own file under `lib/edoxen/`. No `require_relative`
-  — all cross-references resolve through Ruby autoload.
+  No `require_relative` in library code — cross-references resolve
+  through Ruby autoload.
+* Each model lives in its own file under `lib/edoxen/`. Models declare
+  `attribute` only — `lutaml-model` auto-emits an identity map (wire
+  name = snake_case attribute name) when no explicit `key_value` block
+  is present. Add a `key_value do; map "wire", to: :attr; end` block
+  only when the wire name differs from the attribute name.
 * `lib/edoxen/enums.rb` is the single source of truth for every enum
   value used by the gem. Both the Ruby model (`attribute :type, :string,
-  values: Enums::ACTION_TYPE`) and `schema/edoxen.yaml` refer to the
-  same constant; `spec/edoxen/schema_enum_sync_spec.rb` asserts equality
-  at runtime.
-* `lib/edoxen/schema_validator.rb` is intentionally small: a
-  `SchemaValidator::ValidationError`, a `validate_file` method, a
-  `validate_content` method, and a `LineMap` module for line-accurate
-  error reporting. Adding new collection paths never requires touching
-  it — the lookup is longest-prefix match against an indent-heuristic
-  line map.
-* `lib/edoxen/cli.rb` is the Thor surface that glues SchemaValidator and
-  `ResolutionCollection.from_yaml` together for the two CLI commands.
+  values: Enums::ACTION_TYPE`) and the schemas reference the
+  same constants.
+* `lib/edoxen/error.rb` defines the unified `Edoxen::ValidationError`
+  — produced by both `SchemaValidator` (with `source: :schema` or
+  `:syntax`) and by model parse rescues in the CLI (with `source:
+  :model`). Carries `file`, `line`, `column`, `pointer`,
+  `message_text`, and `source`.
+* `lib/edoxen/schema_validator.rb` is intentionally small: two
+  validate methods, a `LineMap` module for line-accurate error
+  reporting (longest-prefix match — no path-shape hardcoding), and
+  date coercion so `json_schemer` can validate `format: date` against
+  YAML-loaded `Date` instances.
+* `lib/edoxen/cli.rb` exposes four Thor commands (`validate`,
+  `normalize`, `validate-meetings`, `normalize-meetings`) that
+  delegate their shared scaffolding
+  (expand/sort/empty/header/loop/tally/summary/exit) to the deep
+  `Edoxen::Cli::Batch` module.
+
+=== Schema ↔ Ruby invariants
+
+Two pairs of runtime specs guard each side of the schema ↔ Ruby
+boundary:
+
+* Resolution side: `schema_enum_sync_spec.rb` +
+  `schema_model_sync_spec.rb` against `schema/edoxen.yaml`.
+* Meeting side: `schema_meeting_enum_sync_spec.rb` +
+  `schema_meeting_model_sync_spec.rb` against `schema/meeting.yaml`.
+
+Drift fails CI immediately, not at fixture-validation time.
 
 == Contributing
 
@@ -192,10 +329,16 @@ Follow the rules in `CLAUDE.md`:
 * All public methods have specs.
 * Specs use real model instances — never `double()`.
 * Serialization goes through `lutaml-model` only — no hand-rolled
-  `to_h`, `from_h`, `to_yaml`, or `to_json` on a model class.
-* Schema and Ruby enum values must agree; the schema_sync_spec catches
-  drift.
-* All changes go through PRs. Never commit to `main`, never push tags.
+  `to_h`, `from_h`, `to_yaml`, or `to_json` on a model class. Declare
+  `attribute`; the wire map is auto-emitted.
+* Schema and Ruby must agree on enum values *and* on property shape.
+  Both `schema_enum_sync_spec` and `schema_model_sync_spec` catch
+  drift at CI time.
+* Library code uses autoload (declared in `lib/edoxen.rb`), never
+  `require_relative`. No `send` to private methods, no
+  `instance_variable_set`/`get`, no `respond_to?` for type checks.
+* All changes go through PRs. Never commit to `main`, never push tags,
+  never add AI attribution to commits.
 
 == License
 

data/TODO.meeting-agenda/01-design-decisions.md

@@ -0,0 +1,132 @@
+# Phase 1 — Design decisions
+
+Priority: **P0** (canonical — blocks every later phase)
+
+## Goal
+
+Lock down the conceptual model before any code lands. Every later
+phase references these decisions; if they shift, downstream work
+reopens.
+
+## Decisions
+
+### D1 — Meeting is the event; Agenda is a document
+
+The previous draft conflated these. Split:
+
+- **Meeting** — the event itself. Identity, time, venue, officers,
+  schedule, deadlines, links to Resolutions.
+- **Agenda** — the business order document produced for the Meeting.
+  Carries items, opening/closing sessions, status (draft/final), and a
+  pointer to the source PDF.
+
+A Meeting *has* an Agenda (`Meeting.agenda: Agenda`). An Agenda is
+meaningless without a Meeting but may be versioned independently
+(draft → final → amended).
+
+### D2 — Schedule ≠ Agenda
+
+- **Schedule** — the time-bound timetable: date, time slot, room,
+  event title. Lives on `Meeting.schedule: ScheduleItem[]`.
+- **Agenda** — the topic-bound business order: numbered/unnumbered
+  items, opening session, closing session. Lives on `Meeting.agenda`.
+
+ISO/TC 154's data already separates these (`schedule[]` and
+`agenda.{opening_session, closing_session, wg_meetings}`). Don't
+collapse them.
+
+### D3 — Linking to Resolutions is by URN, not embedding
+
+- `Meeting.resolution_refs: String[]` — URNs of resolution
+  collections produced by this meeting.
+- `ResolutionCollection.metadata.meeting_urn: String` — back-reference.
+
+Rationale: meetings and resolutions have different lifetimes (an
+agenda exists weeks before the meeting; resolutions exist only after
+adoption). Embedding forces re-serialization of the whole meeting when
+one resolution is amended. URN linking matches how both repos already
+work (ISO: `_data/events/` separate from `_data/resolutions/`; OIML:
+the metadata block of a ResolutionCollection already comments its
+meeting URN).
+
+### D4 — Localization parallels the Resolution pattern
+
+`Meeting.localizations: MeetingLocalization[]` carries per-language
+`title`, `general_area`, `practical_info`. ISO 639-3 + ISO 15924,
+identical to `Localization` for Resolutions.
+
+The schedule itself stays language-agnostic at the structural level
+(date, time, room); localized `event` and `description` text live
+inside `MeetingLocalization`. **v1 decision:** keep schedule
+monolingual on `ScheduleItem` (event/description as plain strings)
+and only localize at the Meeting level. If a future caller needs
+per-schedule-item localization, add `ScheduleItemLocalization`
+then — don't pre-bake it.
+
+### D5 — Reuse existing edoxen types
+
+| Concept | Reuse |
+|---|---|
+| Identifier | `StructuredIdentifier` |
+| Source URL | `SourceUrl` (extend with optional `kind` in this work) |
+| Validation error | `Edoxen::ValidationError` |
+| CLI scaffold | `Edoxen::Cli::Batch` |
+
+### D6 — Meeting/Agenda have their own top-level containers
+
+- `MeetingCollection` — top-level wrapper for a YAML containing many
+  meetings (parallel to `ResolutionCollection`).
+- Single-meeting files are also valid (`Meeting` directly under root,
+  detected by `oneOf` in JSON-Schema).
+
+### D7 — Wire-name are snake_case
+
+LUTAML uses camelCase notation; YAML wire is snake_case. Same
+convention as the rest of edoxen.
+
+### D8 — All enums closed and synced
+
+New enums land in `Edoxen::Enums` and the schema's `$defs/<EnumName>`
+blocks. Both `schema_enum_sync_spec` and `schema_model_sync_spec`
+extend to cover them.
+
+## Type inventory (MECE check)
+
+| Concept | Owns |
+|---|---|
+| `Meeting` | the event (identity, time, venue, officers, agenda, schedule) |
+| `MeetingLocalization` | per-language content for a Meeting |
+| `MeetingCollection` | top-level wrapper for many Meetings |
+| `MeetingRelation` | directed link between two Meetings |
+| `Agenda` | the business order document |
+| `AgendaItem` | one entry on an Agenda |
+| `Location` | venue geography |
+| `Person` | identity + contact + affiliation |
+| `HostRef` | typed reference to an organization |
+| `ScheduleItem` | one entry in the timetable |
+| `Deadline` | a time-bound requirement |
+| `DateRange` | start + end pair |
+| `Reference` | generic document reference (used by AgendaItem) |
+
+13 new classes. No overlaps.
+
+## Enums
+
+| Enum | Values |
+|---|---|
+| `MEETING_TYPE` | plenary, working_group, task_group, ad_hoc, joint, conference_session |
+| `MEETING_STATUS` | upcoming, completed, cancelled |
+| `AGENDA_STATUS` | draft, final, amended, cancelled, superseded |
+| `AGENDA_ITEM_KIND` | numbered, unnumbered, header, opening, closing |
+| `AGENDA_ITEM_OUTCOME` | discussed, resolved, deferred, adopted, withdrawn |
+| `HOST_TYPE` | national_body, liaison, associate, organizer |
+| `MEETING_RELATION_TYPE` | continues_from, continues_to, joint_with, supersedes, supersedes_by, rescheduled_from, rescheduled_to |
+| `SOURCE_URL_KIND` | agenda_pdf, minutes_pdf, resolutions_pdf, report_pdf, register_url, landing_page |
+
+8 new enums.
+
+## Acceptance criteria
+
+- [x] D1–D8 written
+- [x] Type inventory listed
+- [x] Enum inventory listed

data/TODO.meeting-agenda/02-lutaml-canonical.md

@@ -0,0 +1,61 @@
+# Phase 2 — Canonical LUTAML in edoxen-model
+
+Priority: **P0**
+
+## Goal
+
+Land the canonical LutaML UML definitions in
+`/Users/mulgogi/src/mn/edoxen-model/models/`. The Ruby gem mirrors
+these files 1:1.
+
+## Deliverables — one `.lutaml` per concept
+
+### Top-level
+
+- `meeting_collection.lutaml` — top-level wrapper.
+- `meeting.lutaml` — the event class.
+- `meeting_localization.lutaml` — per-language content.
+- `meeting_relation.lutaml` — cross-meeting link.
+
+### Sub-structures
+
+- `agenda.lutaml`
+- `agenda_item.lutaml`
+- `schedule_item.lutaml`
+- `deadline.lutaml`
+- `date_range.lutaml`
+- `location.lutaml`
+- `person.lutaml`
+- `host_ref.lutaml`
+- `reference.lutaml`
+
+### Enums (one per file, mirroring existing convention)
+
+- `meeting_type.lutaml`
+- `meeting_status.lutaml`
+- `agenda_status.lutaml`
+- `agenda_item_kind.lutaml`
+- `agenda_item_outcome.lutaml`
+- `host_type.lutaml`
+- `meeting_relation_type.lutaml`
+- `source_url_kind.lutaml`
+
+### Removed
+
+- `meeting-model.adoc` — superseded; the LUTAML files are now
+  authoritative. Move to `meeting-model.adoc.deprecated` rather than
+  delete (history preservation).
+
+## Attribute shape per class
+
+(See Phase 1 for the canonical field list. Each `.lutaml` declares
+attributes exactly matching the Ruby model in Phase 3 — types are
+LUTAML notation, wire names are snake_case per D7.)
+
+## Acceptance criteria
+
+- [ ] 21 new `.lutaml` files in `models/`.
+- [ ] `README.adoc` updated: new "Meeting model" section, file index
+      extended.
+- [ ] Old `meeting-model.adoc` renamed to `.deprecated`.
+- [ ] Commit + PR to `edoxen/edoxen-model`.

data/TODO.meeting-agenda/03-ruby-models.md

@@ -0,0 +1,73 @@
+# Phase 3 — Ruby model mirror in edoxen
+
+Priority: **P0**
+
+## Goal
+
+One Ruby class per LUTAML file. autoload entries in `lib/edoxen.rb`.
+No `require_relative` in library code. No `send` to private, no
+`instance_variable_set`/`get`, no `respond_to?` for typing.
+
+## Deliverables — `lib/edoxen/*.rb`
+
+### New files
+
+- `meeting_collection.rb` — top-level wrapper.
+- `meeting.rb` — the event class.
+- `meeting_localization.rb`
+- `meeting_relation.rb`
+- `agenda.rb`
+- `agenda_item.rb`
+- `schedule_item.rb`
+- `deadline.rb`
+- `date_range.rb`
+- `location.rb`
+- `person.rb`
+- `host_ref.rb`
+- `reference.rb`
+
+### Modified files
+
+- `lib/edoxen.rb` — add 13 autoload entries.
+- `lib/edoxen/enums.rb` — add 8 new enum constants.
+- `lib/edoxen/resolution_metadata.rb` — add `meeting_urn: String`
+  field (back-reference to a Meeting).
+- `lib/edoxen/source_url.rb` — add optional `kind: String, values:
+  Enums::SOURCE_URL_KIND` field (orthogonal addition; existing
+  fixtures without it still parse).
+
+### Class shape
+
+Each class is `Lutaml::Model::Serializable` with:
+
+- `attribute :name, Type, **opts` declarations only.
+- No explicit `key_value do; map ...; end` block — lutaml-model
+  auto-emits identity maps (established in v0.3.1 refactor).
+- Enum-typed attributes use `values: Enums::FOO`.
+- Convenience accessors added where the lookup is non-trivial
+  (parallel to `Resolution#in_language`).
+
+### Convenience accessors
+
+- `Meeting#in_language(code, fallback: false)` — exact-match lookup
+  on `localizations`.
+- `Meeting#primary_localization` — English-or-first.
+- `Meeting#find_agenda_item(label)` — by label string.
+- `MeetingCollection#find_by_urn(urn)` — URN lookup.
+- `MeetingCollection#find_by_identifier(prefix:, number:)` —
+  structured-identifier lookup.
+
+### Invariants
+
+- `Meeting.identifier` is `StructuredIdentifier[1..*]` (required by
+  schema; permissive in model).
+- `Meeting.localizations[*].language_code` matches `^[a-z]{3}$`
+  (schema-enforced).
+- `Meeting.date_range` is a `DateRange` with optional `start`/`end`.
+
+## Acceptance criteria
+
+- [ ] 13 new Ruby files, each ≤40 lines.
+- [ ] No `require_relative` in any new file.
+- [ ] `bundle exec rspec` passes (existing 197 examples).
+- [ ] `bundle exec rubocop` clean.

data/TODO.meeting-agenda/04-schema.md

@@ -0,0 +1,34 @@
+# Phase 4 — JSON-Schema
+
+Priority: **P0**
+
+## Goal
+
+A separate `schema/meeting.yaml` for Meeting/Agenda validation. The
+existing `schema/edoxen.yaml` (Resolutions) is untouched.
+
+## Why a separate schema file
+
+- Resolutions and Meetings are different document types with
+  different lifecycles.
+- Different CLI subcommands validate each.
+- Avoids touching the existing schema (which is referenced by 1,241
+  OIML fixtures via `yaml-language-server: $schema=`).
+
+## Deliverables
+
+- `schema/meeting.yaml` — full JSON-Schema (draft-07).
+  - Root: `oneOf` — `MeetingCollection` OR `Meeting`.
+  - `$defs` for every class + every enum.
+  - `additionalProperties: false` everywhere.
+  - `required` on identifier + type for Meeting.
+  - `pattern` on `language_code` (`^[a-z]{3}$`), `script`
+    (`^[A-Z][a-z]{3}$`), `country_code` (`^[A-Z]{2}$`).
+  - `minItems: 1` on `Meeting.identifier`.
+
+## Acceptance criteria
+
+- [ ] `schema/meeting.yaml` exists and is valid JSON-Schema draft-07.
+- [ ] `Edoxen::SchemaValidator.new("path/to/meeting.yaml")` loads it.
+- [ ] All Phase 5 fixtures validate cleanly.
+- [ ] All Phase 6 specs (including schema enum sync) pass.