iev 0.4.6 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5d3397238922342cdb3fb6b5adcf8fa969d2b3d6510742485d7d2a20b1d1a12
-  data.tar.gz: 6a82e64e1201a9a2f04cff66d024de1b23643030ce6e37f26ef09bb2ad334b10
+  metadata.gz: a016c3e0df9de5b20b48d9354f3a61ebbc604ac94e07b116a07ce2023b244eea
+  data.tar.gz: badb0152246599074ab74131274b70972f8ab8fa3dd1e4b49b06bd38dde81a33
 SHA512:
-  metadata.gz: be3b984bd46c791580a73644e88dccca4b98b708ce0e28c50f72e822abb609573455201b633d0e4d791b9271cdecb20a555b11cc674dda46bde90fcf7eaccb74
-  data.tar.gz: e56796a853c58aae578dd5c4fe3fbaf3e18115e1a08e22feb7d5f876d9521dee4d27fb734fb05baa12e297b1dc9ac89b67197cad0b51695b2224c3fdb622f3a5
+  metadata.gz: 6a1527631c2f47363372dca4f12f9c3b4026a3d936ecfabf8336dc061c3a188fb79d1e4797aa028c11d13936ef6164d09c2e396b50315cc532e01cda65f30d08
+  data.tar.gz: 7d1c71fcb8b1f87bbc7787688b8937780cb775fc43a6e7058d59f41a269cc2f4bdcd725ce303bc160ae5317505465ba88bd0c453d4cf311063f3207ed8e99bd3

data/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"7e802925-11d5-47e6-9ff2-7e151d3b2dfb","pid":23315,"procStart":"Wed Jul  8 10:33:56 2026","acquiredAt":1783506837511}

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-06-13 04:18:23 UTC using RuboCop version 1.86.1.
+# on 2026-06-22 10:01:24 UTC using RuboCop version 1.86.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,37 +11,7 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'iev.gemspec'
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'spec/iev/exporter_spec.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleAlignWith.
-# SupportedStylesAlignWith: either, start_of_block, start_of_line
-Layout/BlockAlignment:
-  Exclude:
-    - 'spec/iev/exporter_spec.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Layout/BlockEndNewline:
-  Exclude:
-    - 'spec/iev/exporter_spec.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
-# SupportedStylesAlignWith: start_of_line, relative_to_receiver
-Layout/IndentationWidth:
-  Exclude:
-    - 'spec/iev/exporter_spec.rb'
-
-# Offense count: 65
+# Offense count: 72
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -65,7 +35,7 @@ Lint/ShadowedException:
   Exclude:
     - 'lib/iev/source_parser.rb'
 
-# Offense count: 26
+# Offense count: 29
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
@@ -94,12 +64,12 @@ Metrics/CyclomaticComplexity:
     - 'lib/iev/term_builder.rb'
     - 'lib/iev/utilities.rb'
 
-# Offense count: 36
+# Offense count: 38
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 73
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 7
@@ -128,15 +98,3 @@ Naming/MethodParameterName:
 Naming/VariableNumber:
   Exclude:
     - 'spec/iev/exporter_spec.rb'
-
-# Offense count: 5
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
-# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
-# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
-# FunctionalMethods: let, let!, subject, watch
-# AllowedMethods: lambda, proc, it
-Style/BlockDelimiters:
-  Exclude:
-    - 'lib/iev/exporter.rb'
-    - 'spec/iev/exporter_spec.rb'

data/CLAUDE.md

@@ -33,7 +33,9 @@ This is a Ruby gem (`iev`) for working with the International Electrotechnical V
 - `SupersessionParser` — parses the REPLACES field for deprecated term relationships.
 - `SubjectAreas` — manages the IEV subject area/section hierarchy. Bundled `data/subject_areas.yaml` contains the area/section tree. URI scheme: `area-{code}` and `section-{code}`.
 - `SubjectAreaConcepts` — builds area and section hierarchy concepts. Uses `ConceptReference` with proper `ref_type` per `ConceptReferenceType`: `"domain"` for thematic area classification, `"section"` for structural section membership. Sets `ConceptData#domain` to area title text.
-- `Exporter` — full export pipeline (Excel/SQLite → Glossarist YAML). Assigns domain and section `ConceptReference` objects via `domain_references_for`. Uses `Glossarist::DatasetRegister` model for `register.yaml`. Sets `schema_version: "3"` on all exported concepts.
+- `Exporter` — full export pipeline (Excel/SQLite → Glossarist YAML). Assigns domain and section `ConceptReference` objects via `domain_references_for`. Uses `Glossarist::DatasetRegister` model for `register.yaml`. Sets `schema_version: "3"` on all exported concepts. Pipeline order: build → subject areas → section relations → figure extraction → reference enrichment → save concepts → save figures → save bibliography → save register.
+- `FigureBuilder` — destructive extraction pass that hoists AsciiDoc image macros (emitted from SIMG tags by `Utilities`) into dataset-shared `Glossarist::Figure` entities. Rewrites inline text to `{{fig:id, display}}` mentions and adds `FigureReference` entries to `ManagedConceptData#figures`. One Figure entity per unique image file; captions merge across languages.
+- `BibliographyBuilder` — collects unique `(source, id)` pairs from every concept's sources (localized and managed) into a `Glossarist::BibliographyData`. Entry ids are normalized with the same rules as `Glossarist::Validation::BibliographyIndex` so consumers can resolve anchors.
 - `Converter::MathmlToAsciimath` — converts MathML markup to AsciiMath using Plurimath.
 - `Utilities` — HTML processing: converts IEV cross-references (`<a href=IEV...>`) to `{{URN, term}}` format (ID first, display text last), handles figures, images, bold tags, and newline normalization.
 
@@ -45,6 +47,14 @@ Per the concept model's `ConceptReferenceType`:
 
 Each concept's `ManagedConceptData#domains` contains both refs. `ConceptData#domain` (a `LocalizedString`) holds the section/area title text. The `ManagedConcept#related` array holds `broader`/`narrower` relationships for the hierarchy tree.
 
+### V3 Output Artifacts
+
+An export produces these files alongside the concepts/ directory:
+- `register.yaml` — `Glossarist::DatasetRegister` with section tree, languages, owner, URN.
+- `bibliography.yaml` — single `bibliography:` key wrapping an array of `BibliographyEntry` objects. Entry `id` is the normalized anchor that `Glossarist::Validation::BibliographyIndex` will resolve against.
+- `figures/{fig-id}.yaml` — one `Glossarist::Figure` per unique image. Each concept carries a `FigureReference` on `ManagedConceptData#figures` and an inline `{{fig:id, display}}` mention in the text where the figure appeared.
+- References on localized concepts are populated by `Glossarist::ConceptEnricher#inject_references`, which scans text for `{{urn:...}}`, `<<xref>>`, and `image::` patterns.
+
 ### Configuration
 
 `Iev.configure` yields a `Config` object with:

data/Gemfile

@@ -3,16 +3,18 @@
 source "https://rubygems.org"
 
 # Use local glossarist-ruby when available for development.
-# Otherwise falls back to released gem (requires >= 2.8.2 for tags support).
+# Otherwise falls back to released gem (requires >= 2.8.15 for
+# BibliographyData, Figure/NonVerbRep, and ConceptEnricher support).
 if File.directory?(File.expand_path("../glossarist-ruby", __dir__))
   gem "glossarist", path: "../glossarist-ruby"
 else
-  gem "glossarist", ">= 2.8.2"
+  gem "glossarist", ">= 2.8.15"
 end
 
 gem "benchmark"
 gem "canon"
 gem "openssl"
+gem "playwright-ruby-client", require: false
 gem "rake"
 gem "rspec"
 gem "rubocop"

data/TODO.reconcile/01-design.md

@@ -0,0 +1,57 @@
+# 01 — Architecture & autoloads
+
+## Audit of current approach (scripts/reconcile.rb)
+
+Problems:
+1. **Monolithic** — 400-line script, module of static methods, no classes
+2. **Not model-driven** — builds raw Hashes instead of Glossarist model objects
+3. **No field-level diff** — knows THAT content changed, not WHAT changed
+4. **No before/after values** — loses the historical content
+5. **No machine-readable change log** — no way to audit changes
+6. **No specs**
+7. **Not MECE** — merge, diff, serialize all mixed together
+8. **Not autoloaded** — everything in a script file
+
+## New architecture
+
+```
+lib/iev/reconciler.rb                      module + autoloads
+lib/iev/reconciler/change.rb               field-level change (field, lang, old, new)
+lib/iev/reconciler/change_set.rb           collection of Change per concept
+lib/iev/reconciler/status_mapper.rb        termbase status -> V3 ConceptStatus
+lib/iev/reconciler/termbase_loader.rb      termbase.yaml -> {code => ManagedConcept}
+lib/iev/reconciler/live_loader.rb          HTML pages -> {code => ManagedConcept}
+lib/iev/reconciler/content_differ.rb       diff two ManagedConcepts -> ChangeSet
+lib/iev/reconciler/concept_merger.rb       merge termbase + live -> ReconciledConcept
+lib/iev/reconciler/reconciled_concept.rb   ManagedConcept + ChangeSet + source
+lib/iev/reconciler/report.rb               dataset-level change reporting
+lib/iev/reconciler/pipeline.rb             orchestration
+```
+
+Each class has ONE responsibility (MECE). The Pipeline composes them.
+
+## History reporting
+
+Three layers:
+
+1. **Model-level** — `ManagedConcept#dates` (accepted/amended/retired),
+   `ManagedConcept#status` (valid/draft/superseded/retired),
+   `ManagedConcept#related` (supersedes/superseded_by).
+
+2. **Concept-level annotations** — Each amended concept gets a
+   `ConceptData#annotations` entry describing what field changed, with
+   before/after text.
+
+3. **Dataset-level report** — Summary statistics + machine-readable
+   change log written to `report/`:
+   - `summary.yaml` — aggregate counts by change type, section, language
+   - `changes.csv` — one row per field-level change
+   - `retired.yaml` — concepts retired since termbase snapshot
+   - `new_concepts.yaml` — concepts added since termbase snapshot
+
+## Checklist
+
+- [x] Audit current approach
+- [x] Design new architecture
+- [x] Create lib/iev/reconciler.rb with autoloads
+- [x] Register in lib/iev.rb

data/TODO.reconcile/02-change-models.md

@@ -0,0 +1,44 @@
+# 02 — Change + ChangeSet models
+
+## Goal
+
+The core of history reporting. A `Change` captures a single field-level
+difference between the termbase snapshot and the live snapshot. A
+`ChangeSet` groups all changes for one concept.
+
+## Change
+
+```ruby
+Change = Struct.new(:code, :field, :language, :old_value, :new_value,
+                    :detected_at, keyword_init: true)
+```
+
+Fields:
+- `code`: IEV code (e.g. "102-01-01")
+- `field`: `:designation` | `:definition` | `:notes` | `:examples` | `:status` | `:language_added` | `:language_removed`
+- `language`: ISO 639-2 code ("eng", "fra", nil for concept-level)
+- `old_value`: the termbase value (nil for additions)
+- `new_value`: the live value (nil for removals)
+- `detected_at`: date the change was observed (mirror date)
+
+## ChangeSet
+
+```ruby
+class ChangeSet
+  include Enumerable
+  def initialize(code)
+  def add(change)
+  def each
+  def empty?
+  def by_field(field)
+  def by_language(lang)
+  def summary  # hash of field => count
+end
+```
+
+## Checklist
+
+- [x] Implement Change (Struct)
+- [x] Implement ChangeSet
+- [x] Spec: ChangeSet query methods
+- [x] Spec: ChangeSet#summary

data/TODO.reconcile/02-termbase-loader.md

@@ -0,0 +1,48 @@
+# 02 — Termbase loader
+
+## Goal
+
+Load `iev-data/termbase.yaml` into a uniform per-code hash keyed by IEV
+code. The termbase is the authoritative source for lifecycle dates and
+historical content.
+
+## What termbase.yaml contains
+
+22,228 concepts in the old ISO/IEV termbase format:
+
+```yaml
+102-01-01:
+  termid: 102-01-01
+  term: equality
+  eng:
+    id: 102-01-01
+    terms: [...]
+    definition: "..."
+    language_code: eng
+    notes: [...]
+    examples: [...]
+    entry_status: Standard
+    date_accepted: '2008-08-01T00:00:00+00:00'
+    date_amended: '2008-08-01T00:00:00+00:00'
+    review_date: '2008-08-01T00:00:00+00:00'
+    review_decision_date: '2008-08-01T00:00:00+00:00'
+    review_decision_event: published
+  fra:
+    ...
+```
+
+## Deliverable
+
+Class: `Iev::Reconciler::TermbaseLoader`
+
+- Loads termbase.yaml (22,228 concepts).
+- Returns a Hash keyed by IEV code string → concept hash.
+- Each concept hash normalizes per-language data into a consistent
+  structure so downstream stages don't need to handle the old format
+  ad-hoc.
+
+## Checklist
+
+- [x] Define TermbaseLoader interface
+- [x] Implement
+- [x] Test: loads all 22,228 codes; sample code has expected fields

data/TODO.reconcile/03-live-loader.md

@@ -0,0 +1,28 @@
+# 03 — Live HTML loader
+
+## Goal
+
+Load the mirrored HTML pages from `iev-data-latest/pages/` using the
+existing `Iev::Scraper::PageParser` to extract structured concept data.
+
+## Source
+
+17,473 HTML pages at `../iev-data-latest/pages/*.html`. Each page is
+the current Electropedia display page for one IEV code.
+
+## Deliverable
+
+Class: `Iev::Reconciler::LiveLoader`
+
+- Walks `Iev::Fetcher::PageStore#each_concept`.
+- For each page, uses `Iev::Scraper::PageParser` to parse into the raw
+  hash that `build_concept_from_raw` expects.
+- Returns a Hash keyed by IEV code → parsed raw hash.
+- Extracts the publication date from the HTML (e.g. "Publication date:
+  2008-08") for concepts not in termbase.
+
+## Checklist
+
+- [x] Define LiveLoader interface
+- [x] Implement
+- [x] Test: sample page parses with expected localized_concepts

data/TODO.reconcile/03-status-mapper.md

@@ -0,0 +1,24 @@
+# 03 — StatusMapper
+
+## Goal
+
+Map termbase `entry_status` strings to Glossarist V3 `ConceptStatus`
+enum values. Stateless, single responsibility.
+
+## Mapping
+
+| Termbase | V3 |
+|----------|-----|
+| Standard / Published / Effective | valid |
+| Draft | draft |
+| Not Valid | notValid |
+| Superseded | superseded |
+| Retired | retired |
+
+Unknown values default to `valid`.
+
+## Checklist
+
+- [x] Implement StatusMapper
+- [x] Spec: all mapped values
+- [x] Spec: unknown defaults to valid

data/TODO.reconcile/04-concept-merger.md

@@ -0,0 +1,45 @@
+# 04 — Concept merger
+
+## Goal
+
+For each code in the union of termbase + live sources, merge the two
+into a single V3 `ManagedConcept` with full lifecycle data.
+
+## Three populations
+
+1. **In both** (~16,643 codes): termbase provides dates/status,
+   live provides current content. If content differs, record an
+   amendment.
+2. **Termbase only** (~5,585 codes): not on live Electropedia → mark
+   `status: retired`, add `ConceptDate(type: retired)`.
+3. **Live only** (~830 codes): not in 2020 termbase → new concept,
+   `ConceptDate(type: accepted)` from HTML publication date.
+
+## Merge rules
+
+| Field | Source |
+|-------|--------|
+| `identifier` | either (same code) |
+| `status` | termbase `entry_status` → mapped to `ConceptStatus` enum |
+| `dates` | termbase `date_accepted`/`date_amended`/`review_date`/`review_decision_date` → `ConceptDate` array |
+| `localized_concepts.designations` | **live** if available, else termbase |
+| `localized_concepts.definition` | **live** if available, else termbase |
+| `localized_concepts.notes/examples` | **live** if available, else termbase |
+| `sources` | live parsed sources (richer) |
+| `related` | termbase supersession data + any extracted from live |
+
+## Status mapping
+
+| Termbase `entry_status` | V3 `ConceptStatus` |
+|--------------------------|---------------------|
+| `Standard` / `Published` | `valid` |
+| `Draft` | `draft` |
+| `Not Valid` | `notValid` |
+| `Superseded` | `superseded` |
+| `Retired` / absent from live | `retired` |
+
+## Checklist
+
+- [x] Define merge rules
+- [x] Implement ConceptMerger
+- [x] Test: in-both, termbase-only, live-only cases

data/TODO.reconcile/04-termbase-loader.md

@@ -0,0 +1,28 @@
+# 04 — TermbaseLoader
+
+## Goal
+
+Load `termbase.yaml` and build `Glossarist::ManagedConcept` objects
+with full lifecycle dates from the old termbase format.
+
+## Input
+
+`iev-data/termbase.yaml` — 22,228 concepts in old ISO/IEV format.
+
+## Output
+
+`Hash<String, Glossarist::ManagedConcept>` keyed by IEV code.
+
+Each ManagedConcept has:
+- `id` = code
+- `status` from StatusMapper
+- `dates` from `date_accepted` + `date_amended` (ConceptDate objects)
+- `localized_concepts` hash with one LocalizedConcept per language
+- Each LocalizedConcept has ConceptData with terms, definition, notes, examples
+
+## Checklist
+
+- [x] Implement TermbaseLoader
+- [x] Spec: loads sample termbase entry correctly
+- [x] Spec: dates extracted properly
+- [x] Spec: multi-language concepts

data/TODO.reconcile/05-content-diff.md

@@ -0,0 +1,45 @@
+# 05 — Content diff detector
+
+## Goal
+
+Detect content changes between the termbase snapshot and the live HTML
+for concepts that exist in both sources. Each detected change becomes
+an amendment record.
+
+## What to diff
+
+Per localized concept (per language):
+
+1. **Designations** (terms): added, removed, or changed text
+2. **Definition**: text content changed
+3. **Notes**: added, removed, or changed
+4. **Examples**: added, removed, or changed
+
+## Output
+
+For each changed field, record:
+
+```ruby
+{
+  field: :definition,
+  language: :eng,
+  old_value: "...",      # from termbase
+  new_value: "...",      # from live
+  changed_at: MIRROR_DATE # the date we captured the live page
+}
+```
+
+These feed into the merger to append `ConceptDate(type: amended)` and
+optionally an annotation describing the change.
+
+## Approach
+
+String normalization before comparison: strip whitespace, normalize
+unicode, ignore case-only differences in designation. Real semantic
+diffs (definition rewrite) vs cosmetic diffs (encoding fix).
+
+## Checklist
+
+- [x] Define diff strategy
+- [x] implement ContentDiff
+- [x] Test: identical → no change; modified definition → one diff

data/TODO.reconcile/05-live-loader.md

@@ -0,0 +1,20 @@
+# 05 — LiveLoader
+
+## Goal
+
+Load live HTML pages and build `Glossarist::ManagedConcept` objects
+using the existing `Iev::Scraper::PageParser`.
+
+## Input
+
+`iev-data-latest/pages/*.html` — 17,473 current Electropedia pages.
+
+## Output
+
+`Hash<String, Glossarist::ManagedConcept>` keyed by IEV code.
+
+## Checklist
+
+- [x] Implement LiveLoader
+- [x] Spec: parses sample HTML page
+- [x] Spec: skips placeholder pages (no localized_concepts)

data/TODO.reconcile/06-content-differ.md

@@ -0,0 +1,32 @@
+# 06 — ContentDiffer
+
+## Goal
+
+Compare two `ManagedConcept` objects and produce a `ChangeSet` with
+field-level differences. This is the core of change reporting.
+
+## What to diff
+
+Per localized concept (per language):
+- `designation` (term text)
+- `definition` (text content)
+- `notes` (added/removed/changed)
+- `examples` (added/removed/changed)
+
+At concept level:
+- `status` (e.g. valid → retired)
+- language added (in live but not termbase)
+- language removed (in termbase but not live)
+
+## Normalization
+
+Before comparison: strip HTML tags, normalize whitespace, normalize
+unicode quotes. Avoid false positives from encoding differences.
+
+## Checklist
+
+- [x] Implement ContentDiffer
+- [x] Spec: identical concepts → empty ChangeSet
+- [x] Spec: definition changed → one Change
+- [x] Spec: language added → one Change
+- [x] Spec: status changed → one Change

data/TODO.reconcile/06-v3-serializer.md

@@ -0,0 +1,42 @@
+# 06 — V3 serializer
+
+## Goal
+
+Serialize the merged `ManagedConcept` objects into Glossarist V3 YAML
+files using the existing `Glossarist::ManagedConceptCollection` API.
+
+## Output
+
+```
+output/
+  concepts/
+    concept-102-01-01.yaml
+    concept-102-01-02.yaml
+    ...
+  register.yaml          # DatasetRegister
+```
+
+Each concept file uses `schema_version: "3"` and the V3 field names
+from the concept model:
+
+```yaml
+---
+schema_version: "3"
+identifier: "102-01-01"
+status: valid
+dates:
+  - type: accepted
+    date: "2008-08-01"
+  - type: amended
+    date: "2008-08-01"
+localized_concepts:
+  eng: ...
+  fra: ...
+related: ...
+```
+
+## Checklist
+
+- [x] Define output layout
+- [x] Implement V3 serializer (reuse ManagedConceptCollection#save)
+- [x] Test: round-trip — load output back, verify fields

data/TODO.reconcile/07-cli-and-run.md

@@ -0,0 +1,27 @@
+# 07 — CLI command + end-to-end run
+
+## Goal
+
+Wire the reconciliation pipeline into a runnable command and execute
+it to produce the final dataset.
+
+## Deliverable
+
+Either:
+- A new Thor CLI command: `iev reconcile --termbase <path> --output <dir>`
+- Or a standalone script: `scripts/reconcile.rb`
+
+The command should:
+1. Load termbase.yaml
+2. Load live HTML from PageStore
+3. Merge + diff
+4. Serialize V3 YAML
+5. Write register.yaml
+6. Report: total concepts, in-both, termbase-only, live-only, amendments detected
+
+## Checklist
+
+- [x] Define command interface
+- [x] Implement
+- [x] Run end-to-end and verify output
+- [x] Spot-check 5 concepts manually (in-both, termbase-only, live-only, with changes)

data/TODO.reconcile/07-concept-merger.md

@@ -0,0 +1,32 @@
+# 07 — ConceptMerger + ReconciledConcept
+
+## Goal
+
+Merge termbase and live concepts into a single `ManagedConcept` with
+full lifecycle data, and package it with its `ChangeSet` in a
+`ReconciledConcept` value object.
+
+## ReconciledConcept
+
+```ruby
+ReconciledConcept = Struct.new(:managed_concept, :change_set, :source,
+                               keyword_init: true)
+# source: :both | :termbase_only | :live_only
+```
+
+## Merge rules
+
+| Source | Behavior |
+|--------|----------|
+| both | live content + termbase dates; if changes detected, add ConceptDate(amended) + annotations |
+| termbase only | mark retired, add ConceptDate(retired), preserve full content |
+| live only | new concept, add ConceptDate(accepted) from publication date |
+
+## Checklist
+
+- [x] Implement ReconciledConcept (Struct)
+- [x] Implement ConceptMerger
+- [x] Spec: merge-both produces live content + termbase dates
+- [x] Spec: termbase-only produces retired status
+- [x] Spec: live-only produces accepted date
+- [x] Spec: changes produce annotation entries