edoxen 0.3.0 → 0.5.0

data/TODO.meeting-agenda/06-specs.md

@@ -0,0 +1,52 @@
+# Phase 6 — Specs
+
+Priority: **P0**
+
+## Goal
+
+Comprehensive spec coverage. One spec file per new model class, plus
+CLI and schema-sync coverage. Real model instances only — no
+`double()`.
+
+## Deliverables — `spec/edoxen/meeting_*_spec.rb` (one per class)
+
+For each of the 13 new classes:
+
+- Construction with explicit attrs.
+- Round-trip YAML serialization.
+- Enum coverage where applicable (one example per enum value).
+- Real-instance types (e.g., `Meeting#agenda` returns an `Edoxen::Agenda`).
+
+## Deliverables — additional specs
+
+- `spec/edoxen/meeting_collection_spec.rb` — top-level container,
+  round-trips, lookup helpers (`find_by_urn`, `find_by_identifier`).
+- `spec/edoxen/meeting_lookup_spec.rb` — `Meeting#in_language`,
+  `Meeting#primary_localization`, `Meeting#find_agenda_item`.
+- `spec/edoxen/schema_meeting_enum_sync_spec.rb` — every enum in
+  `schema/meeting.yaml` `$defs` matches the corresponding
+  `Edoxen::Enums::*` frozen array.
+- `spec/edoxen/schema_meeting_model_sync_spec.rb` — every Ruby
+  Meeting-related class has matching properties/collection flags in
+  `schema/meeting.yaml` `$defs`.
+- `spec/edoxen/cli_meetings_spec.rb` — `validate-meetings` and
+  `normalize-meetings` subcommands, spawned via `Open3.capture3`
+  against the new fixtures.
+- `spec/edoxen/schema_validator_meeting_spec.rb` — SchemaValidator
+  constructed with the meeting schema path; happy path + each error
+  type (additionalProperties, required, enum, pattern, type).
+
+## Style rules
+
+- Real model instances only — no `double()`.
+- Each example ≤ 10 lines.
+- Round-trip examples cover every fixture.
+
+## Acceptance criteria
+
+- [ ] One spec file per new class (13 files).
+- [ ] +5 additional specs (collection, lookup, schema enum sync,
+      schema model sync, CLI).
+- [ ] +1 schema_validator spec for the meeting schema path.
+- [ ] `bundle exec rspec` — 0 failures (existing 197 + new ≈ 80+).
+- [ ] `bundle exec rubocop` clean.

data/TODO.meeting-agenda/07-cli.md

@@ -0,0 +1,55 @@
+# Phase 7 — CLI integration
+
+Priority: **P1**
+
+## Goal
+
+Add `validate-meetings` and `normalize-meetings` subcommands. Reuse
+the existing `Edoxen::Cli::Batch` deep module — no scaffold
+duplication.
+
+## Deliverables
+
+- `lib/edoxen/cli.rb` — two new subcommands:
+
+```ruby
+desc "validate-meetings YAML_FILE_PATTERN",
+     "Validate Meeting/Agenda YAML file(s) against schema/meeting.yaml."
+
+def validate_meetings(pattern)
+  validator = SchemaValidator.new(meeting_schema_path)
+  Batch.run(self, pattern, header: "🔍 Validating meetings") do |file|
+    errors = validator.validate_file(file) + collect_meeting_model_errors(file)
+    errors.empty? ? Batch::Result.ok("VALID") : Batch::Result.bad(errors.map(&:to_clickable_format))
+  end
+end
+
+desc "normalize-meetings YAML_FILE_PATTERN",
+     "Round-trip Meeting YAML file(s) through the model (--output DIR | --inplace)."
+
+option :output, type: :string
+option :inplace, type: :boolean
+
+def normalize_meetings(pattern)
+  # Same shape as normalize — uses Batch.run
+end
+```
+
+- `lib/edoxen/cli.rb` private: `meeting_schema_path`,
+  `collect_meeting_model_errors`.
+
+## Why separate subcommands
+
+- Different root schema, different model parser.
+- `validate` (existing) is for ResolutionCollection; backward
+  compatibility preserved.
+- Future: a `validate-all` that auto-detects via `oneOf` if needed.
+
+## Acceptance criteria
+
+- [ ] `edoxen validate-meetings PATTERN` exits 0 on valid fixtures.
+- [ ] `edoxen validate-meetings PATTERN` exits non-zero + lists
+      errors on invalid input.
+- [ ] `edoxen normalize-meetings PATTERN --output DIR` round-trips.
+- [ ] Existing `validate` and `normalize` (for Resolutions) unchanged.
+- [ ] `edoxen help` lists both pairs of commands.

data/TODO.meeting-agenda/08-docs.md

@@ -0,0 +1,35 @@
+# Phase 8 — Documentation
+
+Priority: **P1**
+
+## Goal
+
+README + CLAUDE.md reflect the Meeting/Agenda model. The canonical
+edoxen-model README documents the new LUTAML files.
+
+## Deliverables — edoxen gem
+
+- `README.adoc`:
+  - New "Meeting & Agenda model" section with ASCII tree.
+  - Quick-start example showing both Resolution and Meeting parsing.
+  - Cross-link to the canonical LUTAML files.
+- `CLAUDE.md`:
+  - Architecture section mentions `Meeting`, `Agenda`, the meeting
+    schema, and the separate CLI subcommands.
+  - Audit checklist extended: schema_model_sync_spec covers both
+    `schema/edoxen.yaml` and `schema/meeting.yaml`.
+
+## Deliverables — edoxen-model
+
+- `README.adoc`:
+  - File index extended with all new `.lutaml` files.
+  - New "Meeting model" section explaining the Meeting/Agenda split,
+    URN linking to Resolutions, and the localization pattern.
+  - Sample meeting YAML mirroring one of the gem's fixtures.
+
+## Acceptance criteria
+
+- [ ] Both READMEs updated.
+- [ ] edoxen CLAUDE.md updated.
+- [ ] Sample YAML in edoxen-model README would pass
+      `edoxen validate-meetings`.

data/TODO.meeting-agenda/09-verify-and-release.md

@@ -0,0 +1,41 @@
+# Phase 9 — Verify, PR, merge, release
+
+Priority: **P0**
+
+## Goal
+
+Land everything via PRs. Verify GHA passes. Merge. Bump edoxen minor
+(new feature) and release.
+
+## Branch / PR plan
+
+| Repo | Branch | PRs against |
+|---|---|---|
+| `metanorma/edoxen-model` | `feat/meeting-agenda-model` | main |
+| `metanorma/edoxen` | `feat/meeting-agenda-model` | main |
+
+Order: edoxen-model first (canonical), then edoxen (mirror).
+
+## Verification gates
+
+Per branch, before pushing:
+
+- [ ] `bundle exec rspec` — 0 failures.
+- [ ] `bundle exec rubocop` — 0 offenses.
+- [ ] `bundle exec exe/edoxen validate-meetings "spec/fixtures/meetings/*.yaml"` — clean.
+- [ ] `bundle exec exe/edoxen normalize-meetings --output /tmp/out` — round-trips.
+- [ ] No AI attribution in any commit.
+- [ ] No TODOs / FIXMEs in committed source.
+- [ ] No transient files (.DS_Store, .bak, .swp).
+
+## Post-merge
+
+- [ ] Trigger `gh workflow run release.yml --ref main -f next_version=minor`
+      on `metanorma/edoxen`.
+- [ ] Confirm new version appears on rubygems.org.
+- [ ] Confirm tag `vX.Y.Z` pushed.
+
+## Why minor (not patch)
+
+The new Meeting/Agenda model is an additive feature. No breaking
+change to existing Resolution APIs. Semver minor on the 0.x line.

data/TODO.meeting-agenda/10-future-enhancements.md

@@ -0,0 +1,72 @@
+# Phase 10 — Future enhancements (not in this release)
+
+Priority: **P2**
+
+These are documented as known-future-work; not executed in this pass.
+Each one would be its own PR.
+
+## P2.1 — Per-schedule-item localization
+
+`ScheduleItemLocalization` carrying per-language `event` and
+`description`. Triggered when a real consumer needs WG meeting titles
+in FR alongside EN.
+
+## P2.2 — Meeting series
+
+`MeetingSeries` carrying `{identifier, name, description}` with
+`Meeting.series_ref: String` (URN). Triggered when navigation across
+ordinals becomes a real use case (ISO/TC 154 plenary history page).
+
+## P2.3 — Contribution model
+
+Replace flat `Person.contributors` with a `Contribution` class
+matching the comment in the original draft (`'contributors should
+defer to Contribution model`). Triggered when we need to distinguish
+"presented" vs "authored" vs "reviewed" contributions per meeting.
+
+## P2.4 — Auto-detect document type in CLI
+
+A single `edoxen validate PATTERN` that auto-detects
+ResolutionCollection vs Meeting via JSON-Schema `oneOf`. Triggered
+when users complain about remembering two subcommand names.
+
+## P2.5 — Cross-document link validation
+
+A spec/assertion that every `Meeting.resolution_refs[*]` URN has a
+matching `ResolutionCollection` somewhere in the data set, and vice
+versa. Triggered when broken links cause real bugs.
+
+## P2.6 — Attendance roster
+
+`Meeting.attendance: Attendance[]` carrying per-person attendance
+records (present/absent/apologies + affiliation). Triggered when a
+consumer needs the full attendance record, not just officers.
+
+## P2.7 — Vote records
+
+`VoteRecord { resolution_ref, person, vote: VoteType }` linked to a
+Meeting. Triggered when ballot-by-ballot transparency becomes a
+requirement.
+
+## P2.8 — Minutes narrative
+
+A `Minutes` class distinct from `Agenda`, capturing the actual
+narrative of what was said (linked Markdown / Asciidoc blocks per
+agenda item). Triggered when the OIML `meetings/` directory starts
+receiving Bulletin scans.
+
+## P2.9 — federation (multi-body)
+
+A `Federation` or `JointMeeting` class for meetings organized by
+multiple bodies (e.g., a JWG with TC 154 + TC 307). Triggered when
+real joint-meeting data lands.
+
+## P2.10 — IANA / ISO 3166-1 / ISO 639-3 / ISO 15924 reference data
+
+Built-in lookup tables to validate `country_code`, `language_code`,
+`script` against the actual standard. Triggered when typo-rate
+becomes painful.
+
+## Acceptance criteria
+
+This file documents intent only; nothing to land in this release.

data/TODO.meeting-agenda/README.md

@@ -0,0 +1,30 @@
+# TODO.meeting-agenda — index
+
+The work to land a canonical Meeting + Agenda + AgendaItem model
+linkable to Resolutions/Decisions across `edoxen` and `edoxen-model`.
+
+## Phases
+
+| # | File | Priority | Status |
+|---|---|---|---|
+| 1 | [01-design-decisions.md](01-design-decisions.md) | P0 | done |
+| 2 | [02-lutaml-canonical.md](02-lutaml-canonical.md) | P0 | pending |
+| 3 | [03-ruby-models.md](03-ruby-models.md) | P0 | pending |
+| 4 | [04-schema.md](04-schema.md) | P0 | pending |
+| 5 | [05-fixtures.md](05-fixtures.md) | P0 | pending |
+| 6 | [06-specs.md](06-specs.md) | P0 | pending |
+| 7 | [07-cli.md](07-cli.md) | P1 | pending |
+| 8 | [08-docs.md](08-docs.md) | P1 | pending |
+| 9 | [09-verify-and-release.md](09-verify-and-release.md) | P0 | pending |
+| 10 | [10-future-enhancements.md](10-future-enhancements.md) | P2 | documented |
+
+## Execution order
+
+Phases 2 → 9 are executed in order. Phase 10 documents known-future-
+work only.
+
+## Branches
+
+- `metanorma/edoxen-model` ← `feat/meeting-agenda-model` (Phase 2)
+- `metanorma/edoxen` ← `feat/meeting-agenda-model` (Phases 3–8)
+- Phase 9 merges both, then releases `edoxen` as a minor bump.

data/lib/edoxen/action.rb

@@ -7,11 +7,5 @@ module Edoxen
     attribute :type, :string, values: Enums::ACTION_TYPE
     attribute :date_effective, ResolutionDate
     attribute :message, :string
-
-    key_value do
-      map "type", to: :type
-      map "date_effective", to: :date_effective
-      map "message", to: :message
-    end
   end
 end

data/lib/edoxen/agenda.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # The business-order document of a Meeting. Distinct from the
+  # timetable (Schedule) — the Agenda orders topics; the Schedule
+  # orders time slots.
+  #
+  # An Agenda may be versioned independently of the Meeting: a draft
+  # agenda circulates weeks before; a final agenda at meeting time;
+  # an amended agenda if items are added during the meeting. The
+  # `status` field captures that lifecycle.
+  class Agenda < Lutaml::Model::Serializable
+    attribute :identifier, StructuredIdentifier, collection: true
+    attribute :status, :string, values: Enums::AGENDA_STATUS
+    attribute :source_doc, :string
+    attribute :items, AgendaItem, collection: true
+    attribute :opening_session, ScheduleItem
+    attribute :closing_session, ScheduleItem
+
+    # Find an agenda item by its label (e.g., "5.2"). Returns nil
+    # when no item matches.
+    def find_item(label)
+      items&.find { |item| item.label == label.to_s }
+    end
+  end
+end

data/lib/edoxen/agenda_item.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # One entry on an Agenda. `label` is the visible identifier (e.g.,
+  # "5.2"); `kind` discriminates numbered/unnumbered/header/opening/
+  # closing; `outcome` records what happened; `resolution_ref`
+  # optionally links to the URN of the resolution this item produced.
+  class AgendaItem < Lutaml::Model::Serializable
+    attribute :label, :string
+    attribute :kind, :string, values: Enums::AGENDA_ITEM_KIND
+    attribute :title, :string
+    attribute :description, :string
+    attribute :references, Reference, collection: true
+    attribute :outcome, :string, values: Enums::AGENDA_ITEM_OUTCOME
+    attribute :resolution_ref, :string
+  end
+end

data/lib/edoxen/approval.rb

@@ -8,12 +8,5 @@ module Edoxen
     attribute :degree, :string, values: Enums::APPROVAL_DEGREE
     attribute :date, ResolutionDate
     attribute :message, :string
-
-    key_value do
-      map "type", to: :type
-      map "degree", to: :degree
-      map "date", to: :date
-      map "message", to: :message
-    end
   end
 end