relaton 3.0.0.pre.alpha.17 → 3.0.0.pre.alpha.19

data/lib/relaton/etsi/CLAUDE.md

@@ -0,0 +1,219 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-etsi is a Ruby gem that retrieves ETSI (European Telecommunications Standards Institute) standards metadata using the Relaton bibliographic item model. It fetches data from the ETSI website and the relaton-data-etsi GitHub repository.
+
+## Commands
+
+```bash
+# Install dependencies
+bin/setup
+
+# Run all tests
+rake spec
+
+# Run a specific test file
+rspec spec/relaton/etsi/bibliography_spec.rb
+
+# Run a specific test by line number
+rspec spec/relaton/etsi/bibliography_spec.rb:15
+
+# Run linter
+rake rubocop
+
+# Interactive console
+bin/console
+
+# Install gem locally
+bundle exec rake install
+```
+
+## Architecture
+
+The codebase is transitioning from `RelatonEtsi` namespace to `Relaton::Etsi` namespace.
+
+### New Architecture (lib/relaton/etsi/)
+
+Uses Lutaml for serialization:
+- `Item` - base bibliographic item inheriting from `Bib::Item`
+- `Bibitem` - for `<bibitem>` XML output (includes `Bib::BibitemShared`)
+- `Bibdata` - for `<bibdata>` XML output (includes `Bib::BibdataShared`)
+- `Ext` - ETSI-specific extension data (marker, frequency, mandate, custom_collection)
+- `Doctype` - ETSI document type with abbreviations (EN, ES, GS, TS, TR, etc.)
+
+### Legacy Architecture (lib/relaton_etsi/)
+
+- `BibliographicItem` - extends `RelatonBib::BibliographicItem`
+- `XMLParser` - parses XML into bibliographic items
+- `HashConverter` - converts hashes to bibliographic items
+- `DocumentType` - document type with type/abbreviation mapping
+
+### Core Components
+
+- `Bibliography` - searches and retrieves standards from relaton-data-etsi index
+- `DataFetcher` - fetches all documents from ETSI website CSV export
+- `DataParser` - parses CSV rows into bibliographic items
+- `Processor` - Relaton processor for integration with the relaton ecosystem
+
+### Data Flow
+
+1. `Bibliography.get(ref)` searches the relaton-data-etsi index
+2. Fetches YAML from GitHub, converts to `Item` using `from_yaml`
+3. `DataFetcher.fetch` pulls CSV from etsi.org, parses with `DataParser`, saves to output folder
+
+### Pubid-backed index-v2
+
+The ETSI index is **pubid-structured** (`index-v2.yaml`/`.zip`): each row's `:id`
+is a `Pubid::Etsi::Identifier` serialized to its `_type: pubid:etsi:{etsi-standard,
+amendment,corrigendum}` hash (the whole published ETSI corpus round-trips on the
+pinned pubid — see the root `CLAUDE.md` pubid-pin note). The rows use the **flat,
+compact** shape (`type`/`number`/`version`/`year`/`month` as scalars under
+`_type`) that the published `relaton-data-etsi` index carries — the ETSI
+`to_hash` flattening (merged from `refactor/flatten-etsi-to-hash`) ships in the
+released pubid `2.0.0.pre.alpha.13` that the gemspec pins. The wiring mirrors NIST/JCGM:
+
+- **Producer** (`DataFetcher`): `index` calls `find_or_create(:etsi, file:
+  "#{INDEXFILE}.yaml", pubid_class: ::Pubid::Etsi::Identifier)`; `#save` parses the
+  docid via `#pubid` and stores the **pubid object** (`index.add_or_update pid,
+  file`) so `Relaton::Index` sorts by id number and serializes each id to its
+  `_type:` hash on save. `#pubid` returns nil (skipping the whole record) for any
+  id it can't parse **or** `to_hash`-serialize, so one malformed record can never
+  abort the crawl or corrupt the index. (No current ETSI record is skipped.)
+- **Consumer** (`Bibliography#search`): parses the reference with
+  `::Pubid::Etsi.parse` and lets a `Pubid::Errors::ParseError` on an unrecognized ref
+  **propagate** (ISO parity — the CLI renders a friendly message, API callers
+  rescue it), then `#best_match` selects with pubid's subset match
+  `pubid === row`. The `pubid` (not a String) lets `Relaton::Index` narrow
+  candidates by number via binary search. A `version` or `date` that the ref
+  omits matches any value, so a bare `ETSI GS ZSM 012` matches every edition
+  and a fully-qualified ref matches only its edition.
+  `max_by { edition_key(row[:id]) }` returns the most recent.
+  Requires pubid `main` (partial-ref parsing, `Pubid::Errors::ParseError` on
+  failure, `subset_strict`).
+- **A part-less reference strips the ROW's parts, it does not ask pubid for
+  "all parts".** pubid declares `parts` strict for ETSI (pubid#408), so a
+  part-less ref matches no part row on its own. `#comparable` therefore
+  matches each row without its parts (`exclude(:part, :subpart, :parts)`, a
+  copy — the cached index id is untouched), and `ETSI EN 300 175` reaches its
+  16 part rows. **Do not use `#to_all_parts` here.** Since pubid#433 "all
+  parts" is a class, and `Pubid::AllPartsIdentifier#===` compares the document
+  alone: it drops the version and the date as well, so
+  `ETSI GR ZSM 011 V1.1.1 (2023-02)` answered with V2.1.1 (2024-09) — 586,487
+  pairs over the fixture. `resolves a fully-qualified part-less reference to
+  that exact edition` in `bibliography_spec.rb` pins it.
+- **A base reference does not reach its supplements.** `===` requires the
+  same class, so `ETSI ETR 310` does not match the corrigendum
+  `ETSI ETR 310/C1`, and a corrigendum of the base (`ETS 300 092-1/C1`) does
+  not match a corrigendum of its amendment (`092-1/A1/C1`). The
+  `matches?(…, ignore:)` it replaced did match them: over the 28,651-row
+  fixture, 298 pairs changed, all of them a supplement row that the old match
+  let in, and 218 of 94,079 references resolved to a newer amendment or
+  corrigendum instead of the document itself (`ETSI ETR 310` →
+  `ETR 310/C1 ed.1 (1996-10)`). `bibliography_spec.rb` pins that case.
+- **`#edition_key` orders on the parsed version, never on the rendered id.** ETSI
+  versions are not zero-padded, so a String comparison of `row[:id].to_s` orders
+  `V9.0.0` above `V19.0.0` and `ed.9` above `ed.11` — it picked the wrong edition
+  for 983 of the 3007 multi-edition documents in the spec fixture, and a bare
+  `ETSI TR 155 919` resolved to the 2010 edition. `Pubid::Etsi::Identifier` is
+  **not** `Comparable` (its `<=>` returns nil), so the key is built from the
+  components: `id.version.version` holds the bare numbers (`"19.0.0"`, or `"9"`
+  for the `ed.N` form) and `id.date` renders as `yyyy-mm` for the tie-break.
+  Both delegate to `base` on a `pubid:etsi:corrigendum`/`amendment` row (162 of
+  them in the fixture), so every row shape keys the same way. The key ignores
+  `is_edition`, which puts `ed.11` above `V1.0.0` — safe because **no** document
+  mixes the two forms (measured: 0 of 28651 fixture rows). Do not put `.to_s`
+  back.
+- **Processor** `#remove_index_file` passes `url: true` and `file:` only. It
+  needs no `pubid_class:`: the delete never reads the index (see
+  `lib/relaton/index/CLAUDE.md`).
+
+### The crawl query keeps superseded editions (`version=1`)
+
+`DataFetcher::SOURCEURL` is the ETSI standards-search query, and
+`relaton-data-etsi/data/` is **exactly** what it returns — `crawler.rb` rebuilds
+`data/` on every run, so a record the query drops cannot be reinstated in the
+data repo. The `version` flag selects editions, not statuses: `version=0`
+returns only the current edition of each branch, `version=1` returns the
+superseded ones as well. The status flags (`withdrawn`, `historical`,
+`superseded`, `onApproval`, `isCurrent`) are a **separate axis** and are already
+all `1` — that is why the dataset carried `Historical` and `Withdrawn` documents
+while still missing older editions (metanorma/metanorma-pdfa#95, which wanted
+`ETSI EN 319 142-1 V1.2.1 (2024-01)` back). `version=0` also still returns
+parallel current branches, so the response's own `superseded`/`new_versions`
+fields, not the major version, are what `version` keys on.
+
+The flavor uses `version=1`. Measured against the live API on 2026-08-27:
+
+| | `version=0` | `version=1` |
+|---|---|---|
+| records | 28625 | 67446 (2.36x) |
+| pages at 50/page | 573 | 1349 |
+| `data/` on disk | 112 MB | ~264 MB |
+| `index-v2.yaml` | 5.0 MB | ~11.8 MB |
+
+Nothing else in the producer needed changing: the version is part of the ETSI
+docid, so `Core::DataFetcher#unique_output_file` gives each edition its own
+filename and `Index::Type#add_or_update` (keyed on `id.to_s`) gives each its own
+row. `spec/etsi/relaton/etsi/data_fetcher_spec.rb` pins the query flag, and pins
+that machinery too — it was already correct, but `version=1` is what makes
+several editions of one document a common case rather than a rare one.
+
+**Ordering rule for the data repo.** This is producer-side only; nothing changes
+for users until `relaton-data-etsi` re-crawls. Do **not** deploy a `version=1`
+crawl until the released `relaton-etsi` gem picks the newest edition. Its
+`Bibliography#search` uses `min_by` on the rendered id, which returns the
+**oldest** match, so a bare `ETSI EN 319 401` would resolve to the 2013 edition
+across the whole corpus. This flavor picks the newest edition (`#best_match`
+orders on `#edition_key`). Also check the crawl against the 6-hour GitHub
+Actions job cap — it roughly doubles — and confirm all three EN 319 142-1
+editions land in `data/` before merging the re-crawl.
+
+### A bad page fails the crawl; it is never skipped
+
+The relaton-data-etsi crawl of 2026-09-30 (run 36761804954) died at about page
+700 with `JSON::ParserError: unexpected character: 'Array'`: data.php answered
+once with PHP's `Array` text in place of JSON. It is transient and server side
+— the code had not changed since the good crawl of 2026-09-28, and a full
+re-crawl on 2026-10-02 gave valid JSON on all 1,353 pages (67,602 records,
+`RowNum` 1..67,602 with no gap). Note also that `curl` gets an HTTP 403 page from
+ETSI's web application firewall; Mechanize's user agent gets JSON.
+
+`DataFetcher#fetch_page` therefore parses the body **inside**
+`fetch_with_retry`: a body that is not a JSON array raises `BadPage`, which is
+retried like a network error. A page still bad after its retries is deferred
+and fetched again after the last page (`DEFERRED_DELAY`); if it is still bad,
+the crawl raises `BadPage` with the page number and the first 200 characters of
+the body, and `index.save` is never reached. Page 1 is not deferred (it gives
+`total_count`). **Do not change this to skip the page:** `crawler.rb` deletes
+`data/` before the crawl and commits what the crawl writes, so a skipped page
+unpublishes 50 documents, while a failed crawl commits nothing and the previous
+data stays live.
+
+The result set is sorted by deliverable number (`sort=1`), not by date, so a
+document that ETSI publishes during the one-hour crawl shifts the later pages
+by one. The page count from page 1's `total_count` would then miss the last
+record, so `fetch_remaining_pages` reads on past it while the pages stay full.
+A record read twice overwrites its own file. Two bounds keep the loop finite
+(data.php answers `[]` past the end today, but the loop must not depend on it):
+a deferred page extends the range by one page only when it lies inside page
+1's `total_count`, and a crawl still reading full pages `MAX_EXTRA_PAGES` past
+that count raises. A deferred page that comes back `[]` inside the range also
+fails the crawl. **Known limit:** a document *removed* during the crawl shifts
+the later pages the other way, so one record can fall onto a page already read.
+Nothing detects that; it is rare, because every status flag is on.
+
+## Testing
+
+- **Index fixture:** `spec/fixtures/index-v2.zip` (pubid `_type:` rows) is loaded
+  into the `Relaton::Index` pool in `before(:suite)` (`spec/support/webmock.rb`):
+  the YAML is written to a temp file and read through
+  `Relaton::Index::Type.new(:etsi, file:, pubid_class: ::Pubid::Etsi::Identifier)`,
+  and `type.index` forces the offline `pubid_class` deserialize before the net is
+  blocked; `actual?` is overridden to match only the remote (`url:`) lookup so the
+  producer-side `find_or_create(:etsi, file:, pubid_class:)` still gets a fresh
+  instance. Regenerate by parsing `index-v1`'s ids through `Pubid::Etsi` into a
+  `pubid_class` `Type` and re-zipping (`_type: pubid:etsi:…` rows).
+Uses RSpec with VCR for HTTP interaction recording. VCR cassettes are in `spec/vcr_cassettes/`. When tests make new HTTP requests, VCR will record them.

data/lib/relaton/etsi/README.adoc

@@ -0,0 +1,137 @@
+= Relaton::Etsi
+
+Relaton::Etsi is a Ruby gem that implements the https://github.com/relaton/relaton-models#bibliographic-item[BibliographicItem model].
+
+You can use it to retrieve metadata of ETSI Standards and access such metadata through the `Relaton::Etsi::Item` object.
+
+== Usage
+
+=== Search for a standard using keywords
+
+[source,ruby]
+----
+require "relaton/etsi"
+=> true
+
+item = Relaton::Etsi::Bibliography.get("ETSI GS ZSM 012 V1.1.1")
+[relaton-etsi] INFO: (ETSI GS ZSM 012 V1.1.1) Fetching from Relaton repository ...
+[relaton-etsi] INFO: (ETSI GS ZSM 012 V1.1.1) Found: `ETSI GS ZSM 012 V1.1.1 (2022-12)`
+=> #<Relaton::Etsi::ItemData:0x0000000125869dd8
+...
+----
+
+=== XML serialization
+
+[source,ruby]
+----
+item.to_xml
+=> "<bibitem id="ETSIGSZSM012V111202212" schema-version="v1.5.6">
+      <fetched>2026-01-24</fetched>
+      <title language="en" script="Latn">Zero-touch network and Service Management (ZSM); Enablers for Artificial Intelligence-based Network and Service Automation</title>
+      <uri type="src">http://webapp.etsi.org/workprogram/Report_WorkItem.asp?WKI_ID=62010</uri>
+      <uri type="pdf">http://www.etsi.org/deliver/etsi_gs/ZSM/001_099/012/01.01.01_60/gs_ZSM012v010101p.pdf</uri>
+      <docidentifier type="ETSI" primary="true">ETSI GS ZSM 012 V1.1.1 (2022-12)</docidentifier>
+      ...
+    </bibitem>"
+----
+With argument `bibdata: true` it outputs XML wrapped by `bibdata` element and adds flavour `ext` element.
+[source,ruby]
+----
+item.to_xml bibdata: true
+=> "<bibdata schema-version="v1.5.6">
+      <fetched>2026-01-24</fetched>
+      <title language="en" script="Latn">Zero-touch network and Service Management (ZSM); Enablers for Artificial Intelligence-based Network and Service Automation</title>
+      <uri type="src">http://webapp.etsi.org/workprogram/Report_WorkItem.asp?WKI_ID=62010</uri>
+      <uri type="pdf">http://www.etsi.org/deliver/etsi_gs/ZSM/001_099/012/01.01.01_60/gs_ZSM012v010101p.pdf</uri>
+      <docidentifier type="ETSI" primary="true">ETSI GS ZSM 012 V1.1.1 (2022-12)</docidentifier>
+      ...
+      <ext schema-version="v0.1.2">
+        <doctype abbreviation="GS">Group Specification</doctype>
+      </ext>
+    </bibdata>"
+----
+
+=== Typed source links
+
+All the ETSI documents have SRC and PDF links. The gem provides a way to access these links through the `RelatonBib::TypedUri` object.
+
+[source,ruby]
+----
+item.source
+=>
+[#<Relaton::Bib::Uri:0x0000000129ea7b38 @content="http://webapp.etsi.org/workprogram/Report_WorkItem.asp?WKI_ID=62010", @language=nil, @locale=nil, @script=nil, @type="src">,
+ #<Relaton::Bib::Uri:0x0000000129ea76d8 @content="http://www.etsi.org/deliver/etsi_gs/ZSM/001_099/012/01.01.01_60/gs_ZSM012v010101p.pdf", @language=nil, @locale=nil, @script=nil, @type="pdf">]
+
+item.source.size
+=> 2
+
+item.source[0].type
+=> "src"
+
+item.source[0].content
+=> "http://webapp.etsi.org/workprogram/Report_WorkItem.asp?WKI_ID=62010"
+
+item.source[1].type
+=> "pdf"
+
+item.source[1].content
+=> "http://www.etsi.org/deliver/etsi_gs/ZSM/001_099/012/01.01.01_60/gs_ZSM012v010101p.pdf"
+----
+
+=== Create bibliographic item from XML
+[source,ruby]
+----
+Relaton::Etsi::Item.from_xml File.read('spec/fixtures/bibdata.xml')
+=> #<Relaton::Etsi::ItemData:0x000000012b68f660
+...
+----
+
+=== Create bibliographic item from YAML
+[source,ruby]
+----
+Relaton::Etsi::Item.from_yaml File.read('spec/fixtures/item.yaml')
+=> #<Relaton::Etsi::ItemData:0x0000000126e34c58
+...
+----
+
+=== Fetch data
+
+This gem uses the https://www.etsi.org as a data source.
+
+The method `Relaton::Etsi::DataFetcher.fetch(output: "data", format: "yaml")` fetches all the documents from the data source and saves them to the `./data` folder in YAML format.
+Arguments:
+
+- `output` - folder to save documents (default './data').
+- `format` - the format in which the documents are saved. Possible formats are: `yaml`, `xml`, `bibxml` (default `yaml`).
+
+[source,ruby]
+----
+require 'relaton/etsi/data_fetcher'
+=> true
+
+Relaton::Etsi::DataFetcher.fetch
+Started at: 2023-12-05 22:44:32 -0500
+Stopped at: 2023-12-05 22:47:55 -0500
+Done in: 204 sec.
+=> nil
+----
+
+=== Logging
+
+Relaton::Etsi uses the relaton-logger gem for logging. By default, it logs to STDOUT. To change the log levels and add other loggers, read the https://github.com/relaton/relaton-logger#usage[relaton-logger] documentation.
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To update the index test fixture (used by tests), run `rake spec:update_index`. This downloads the latest `index-v2.zip` (pubid-structured `_type: pubid:etsi:…` rows) from the https://github.com/relaton/relaton-data-etsi[relaton-data-etsi] repository.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/relaton/relaton-etsi.
+
+== License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/relaton/evs/CLAUDE.md

@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-evs retrieves Estonian standardisation (EVS, Eesti Standardimis- ja
+Akrediteerimiskeskus) bibliographic data using the Relaton model. Like CEN/BSI,
+it publishes **no index and has no data repo**: the flavor **scrapes** the EVS
+e-shop (`www.evs.ee`) with Mechanize. Reference handling is entirely
+`Pubid::Evs` (the `:evs` flavor, registered in pubid's registry). EVS records
+are dominated by **adoptions**: `EVS-EN …` adopts a European document,
+`EVS-EN ISO …` a European adoption of an international one, `EVS-ISO …` /
+`EVS-IEC …` adopt international documents directly. The adoption is expressed
+with `adoptedFrom` relations parsed from the page's "Base Documents" group.
+
+## Development
+
+```bash
+bundle exec rake spec:evs                       # the EVS suite
+cd spec/evs && bundle exec rspec -I . relaton/evs/docidentifier_spec.rb
+```
+
+(No gem-local rubocop config; the monorepo root config applies.)
+
+## Architecture
+
+Namespace: `Relaton::Evs`. This is the **BSI/CEN shape**: parse the query with
+pubid, select the hit with pubid, back the `Docidentifier` with pubid. No
+`INDEXFILE`, no `pubid_class:`, no data repo. **Don't add an index** (unless a
+`relaton-data-evs` repo appears — relaton#164 tracks that possibility).
+
+Retrieval flow:
+
+1. **Bibliography** (`lib/relaton/evs/bibliography.rb`) — `get(code, year,
+   opts)` / `search` / `parse`. `parse` wraps `Pubid::Evs.parse` and **raises**
+   on an unrecognized query (root CLAUDE.md law); only the data side rescues,
+   in `Hit#pubid`. `get` keeps an early `nil` for an **empty** reference and
+   accepts the flavor's own pubid without mutating it (`Relaton::Db` hands it
+   the parse it routed). Transport errors are rescued **by name**
+   (`Net::ReadTimeout`, `Net::OpenTimeout` → `Relaton::RequestError`, which
+   `Db#net_retry` retries).
+2. **HitCollection** (`hit_collection.rb`) — the search is a **direct slug
+   probe**, not a form submit: the catalogue URL is the printed reference
+   slugified (`EVS-EN 18216:2026` → `/en/evs-en-18216-2026`), so the product
+   page exists iff the reference denotes a published document. A miss
+   **redirects** to `/page-not-found` (HTTP 302, followed by Mechanize) — that
+   redirect target is the "no hit" signal; a hard 4xx/5xx raises
+   `Mechanize::ResponseCodeError` and is a miss (`hits` rescues to `[]`).
+   The `et`/`et-en` language codes probe the `/et/` locale, which serves the
+   Estonian-language product.
+   - **The hit's `code` keeps the language code** (only the slug derivation
+     strips it): the filter `query === hit.pubid` needs the language ON the
+     hit for a language-carrying query to match its own record.
+   - A reference **without a year** probes `…-<number>` and misses — the
+     catalogue URL always carries the year. "Not found." is honest there; do
+     not add a search-endpoint fallback without evidence the shop renders one
+     server-side (its search is client-rendered).
+   - Slug shapes verified against the live catalogue: plain `EVS 945:2023`,
+     `EVS-EN 16798-1:2019`, `EVS-EN ISO 14001:2026`, the ETSI face
+     `EVS-EN 301 406-1 V3.2.1:2026`, `EVS-EN IEC 61000-4-30:2026`.
+3. **Hit** (`hit.rb`) — `item` lazy-loads the detail page via the scraper;
+   `pubid` memoizes the hit code parsed with pubid and is **nil** when the
+   grammar cannot read it.
+4. **Scraper** (`scraper.rb`) — Mechanize/XPath over the product page:
+   `h1` → docidentifier, `h2.product-title` → title (`Bib::Title.from_string`
+   splits " - " into intro/main — it returns an Array, don't re-wrap), the
+   "Valid from dd.mm.yyyy" badge → `published` date, "Base Documents" →
+   `adoptedFrom` relations (a double adoption lists both bases in ONE text
+   node, `ISO 14001:2026; EN ISO 14001:2026` — split on the semicolon), the
+   scope tab (`div#tab-1`) → abstract, ICS group links → `Ext.ics` via
+   `Isoics`. Contributor/copyright: the EVS organization (publisher); place
+   Tallinn.
+5. **ItemData / models** (`item_data.rb`, `model/`) — `Relaton::Evs::ItemData`
+   extends `Relaton::Bib::ItemData`; `Ext` adds a `StructuredIdentifier`
+   (docnumber/partnumber from the pubid **root**, agency "EVS"). There is no
+   `relaton-model-evs` gem, so `Ext` does not override `get_schema_version`
+   (inherits the nil default, like the other ten model-less flavors). The
+   **shared ext grammar requires a `doctype`** — `fetch_doctype` always emits
+   one (`standard`; `technical-specification`/`technical-report` for the
+   `EVS-TS`/`EVS-TR` faces), or Jing fails on `relaton-evs-compile.rng`.
+
+### `#root` is the accessor that answers for every form
+
+A `NationalAdoption` (`EVS-EN ISO 9001:2015/A1:2024`) holds the origin
+standard's number and year behind its `base` chain (base = the CEN/CENELEC
+document; `AdoptedEuropeanNorm#adopted` = the ISO document; `#root` recurses),
+so the year, number and part are read from `#root`. An `InternationalAdoption`
+(`EVS-ISO 9001:2015`) or `EstonianStandard` (`EVS 945:2023`) is its own root.
+
+### `Docidentifier` — the year rule
+
+`Relaton::Evs::Docidentifier` (`model/docidentifier.rb`, `< Bib::Docidentifier`)
+parses its `content` into `@pubid` (DATA side: lazy `require "pubid"`, rescues
+`LoadError`/`StandardError`; a foreign value stays verbatim with `@pubid` nil).
+`Pubid#exclude` returns a **copy**, so each mutator replaces `@pubid` and
+re-renders through the aliased `store_content`. **`remove_date!` drops the
+LAST year**: on a supplement (`EVS-EN ISO 9001:2015/A1:2024`) the supplement's
+year goes first (`exclude(:supplement_year)` → `…/A1`), the base year only
+when there is none. `to_all_parts!` wraps in pubid's `AllParts` — `content`
+stays the part-and-date-stripped string on purpose; `#pubid` renders the
+"(all parts)" marker.
+
+### Printed separator is identity
+
+`EVS EN 18216:2026` (space) and `EVS-EN 18216:2026` (hyphen) parse to the same
+class and root, but each renders back **as written** — pubid preserves the
+input's separator. Never compare EVS identifiers by `to_s`; compare by parse
+(`===`, `root.number`).
+
+### Registration
+
+`Processor` (`processor.rb`) sets `@short = :relaton_evs`, `@prefix = "EVS"`,
+`@pubid_flavor = :Evs` (prefixes sourced from `Pubid::Evs.prefixes`) and
+`@defaultprefix = %r{^EVS[\s-]}`. It lazy-`require_relative`s `../evs` inside
+each method, like every other flavor (`spec/relaton/lazy_loading_spec.rb`
+guards that). `lib/relaton.rb` autoloads `:Evs`; `Db::Registry::SUPPORTED_GEMS`
+lists `relaton/evs`; `grammar/relaton-evs(-compile).rng` mirrors the CEN pair
+(the shared `biblio-standoc` ext already models doctype/flavor/ics/
+structuredidentifier, and its `DocRelationType` carries `adoptedFrom`).

data/lib/relaton/evs/README.adoc

@@ -0,0 +1,27 @@
+= relaton-evs
+
+EVS is the Estonian national corpus of the https://github.com/relaton/relaton[Relaton] bibliographic model.
+
+Retrieves Estonian standardisation records (EVS, Eesti Standardimis- ja Akrediteerimiskeskus) from the https://www.evs.ee[EVS e-shop].
+
+- Plain Estonian standards: `EVS 945:2023`, the `EVS-TS`/`EVS-TR` faces
+- National adoptions: `EVS-EN 18216:2026`, `EVS-EN ISO 9001:2015/A1:2024`, `EVS-EN ISO/IEC 27017:2026`
+- Direct international adoptions: `EVS-ISO 9001:2015`, `EVS-IEC 62368-1:2020`
+- Language codes: `EVS 811:2018 et`, `et-en`
+
+Reference parsing is entirely https://github.com/pubid/pubid[`Pubid::Evs`]; adoptions are expressed as `adoptedFrom` relations to the base documents.
+
+== Usage
+
+[source,ruby]
+----
+require "relaton/evs"
+
+item = Relaton::Evs::Bibliography.get "EVS-EN ISO 14001:2026"
+#=> #<Relaton::Evs::ItemData …> with adoptedFrom relations to
+#   "ISO 14001:2026" and "EN ISO 14001:2026"
+----
+
+== Development
+
+Run the suite from the repository root: `bundle exec rake spec:evs`.

data/lib/relaton/gb/CLAUDE.md

@@ -0,0 +1,47 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-gb retrieves Chinese National Standards (Guobiao — `GB`, `GB/T`, `GB/Z`, plus social-org and sector standards) using the Relaton model. It scrapes several Chinese government portals (`openstd.samr.gov.cn`, `ttbz.org.cn`, `std.gov.cn`) with Mechanize. Depends on relaton-iso for ISO-based item/extension models, and on Chinese-specific classifiers (`cnccs`, `gb-agencies`).
+
+## Development
+
+```bash
+bundle exec rake        # default task → rspec
+bundle exec rspec spec/relaton/gb/bibliography_spec.rb   # single file
+```
+
+(RuboCop is configured via the shared `.hound.yml`; the monorepo root config applies otherwise.)
+
+## Architecture
+
+Namespace: `Relaton::Gb`. Note: GB places its model classes at the top of `lib/relaton/gb/` (`item.rb`, `bibitem.rb`, `bibdata.rb`, `ext.rb`, …) rather than under a `model/` subdir.
+
+Retrieval flow:
+
+1. **Bibliography** (`lib/relaton/gb/bibliography.rb`) — `get`/`search` dispatch by prefix: `GB*` → `GbScraper` (openstd.samr.gov.cn), `T/` → `TScraper` (ttbz.org.cn), others → `SecScraper` (std.gov.cn).
+2. **Scrapers** (`scraper.rb` + `gb_scraper.rb` / `t_scraper.rb` / `sec_scraper.rb`) — scrape the relevant portal for hits, then scrape the detail page into an `ItemData`.
+3. **HitCollection / Hit** (`hit_collection.rb`, `hit.rb`, extend the `Relaton::Core` bases) — `Hit#item` lazy-loads the document; a hit holds `pid`, `docref`, `release_date`, `status`.
+4. **Item / ItemData / Ext** (`item.rb`, `item_data.rb`, `ext.rb`) — `Item` extends `Bib::Item`; `Ext` carries GB-specific fields (`gbtype`, `ccs`, `stagename`, `plannumber`). Supporting models: `gb_type.rb`, `ccs.rb` (Chinese classification), `stage_name.rb`, `committee.rb`, `structured_identifier.rb`.
+5. **Processor** (`lib/relaton/gb/processor.rb`) — registry integration; `@prefix = "CN"`, `@defaultprefix = %r{^(GB|GB/T|GB/Z) }`, `@pubid_flavor = :Gb`. Lazy-`require_relative`s `../gb` in its methods.
+
+## Identifiers (pubid)
+
+GB parses identifiers with `Pubid::Gb::Identifier`. It publishes no index, so it has no `INDEXFILE` and no `pubid_class:` (the BSI/CEN shape, see the root `CLAUDE.md`). The attributes it reads are `publisher`, `mandate`, `number`, `part`, `year` and `all_parts`.
+
+- **Query side raises.** `Bibliography.get` parses the caller's code without a rescue, so a reference that is not a GB identifier raises `Pubid::Errors::ParseError`. `get` also takes the `Pubid::Gb::Identifier` that `Relaton::Db` parsed (relaton#205) and never mutates it: an `AllParts` pubid (or a String `(all parts)`) sets `all_parts` and unwraps its identifier, and every change after that is on the `exclude(:year)` copy. The year comes from the argument or from `pubid.year`; `all_parts` sets `part = "1"` on the copy to find part 1. `search` still routes on the raw string (`GB|GJ|GS` → `GbScraper`, `T/…` → `TScraper`, else `SecScraper`), so the portal for each reference and the cassettes are unchanged.
+- **Hit filter.** `search_filter` parses each `hit.docref` (rescued: a docref is data; an unparseable one drops the hit) and keeps the hits that `query.matches?`. It ignores `:year` only when the query has no year. It **never** ignores `:part`: `GB/T 20223` and `GB/T 20223.1` are two documents, and `gb_spec.rb` asserts that `GB/T 20223-2006` does not return `GB/T 20223.1-2006`. This is a deliberate departure from the migration hand-off, which proposed to ignore a part the query omits. It also stops `GB/T 1.1` from matching `GB/T 1.10`, which the old substring compare allowed.
+- **`Docidentifier`** (`docidentifier.rb`) follows the CEN/OMG shape: `content=` parses into `@pubid` (rescued, data side), and the mutators replace the pubid with an `exclude` copy and write back through `store_content`. `to_all_parts!` excludes part and year, sets `all_parts`, and pubid renders the ` (all parts)` suffix itself (and parses it back). A nil pubid makes every mutator a no-op.
+- **Scrapers** (`scraper.rb`) read the docref through a rescued `docref_pubid`. `get_prefix` keys `yaml/prefixes.yaml` with the first segment of `publisher` (a `Pubid::Components::Publisher`, so read it as `publisher.to_s`; `T/GZAEPI` → `T`). An unknown key gives nil, and `get_gbtype` keeps a nil prefix rather than raising — a portal docref is data. `get_mandate` maps `mandate` `T` → recommended, `Z` → guidelines, nil → mandatory. `get_contributors` passes `publisher.to_s` to `gb_agencies`, which names the same organization for `GB` and `GB/T`. `parse_docref` returns `[id without part and year, part, year]`; the first value is `plannumber`.
+- **Pubid traps.** `Pubid::Gb` accepts any upper-case publisher code (`ISO 123` parses), so use `foo` or `GB/T` for a parse-error example. `year` is a reader over `date` (no `year=`); set it with `date = Pubid::Components::Date.new(year:)`. Local (`DB11/T`) forms do not parse. pubid PR #388 (`dcea7380`) renamed `publisher_code` to the `publisher` component, added the year to `to_hash`, and made `GBn` parse; a pubid older than that breaks this flavor. pubid renders an em dash (`T/GZAEPI 001—2018`) as a hyphen; the fixture `tgzaepi_001_2018.xml` still records the em dash, and its spec is pending until pubid decides.
+- **Prefix register.** `@pubid_flavor = :Gb` sources `Relaton.prefix_flavor` from `Pubid::Gb.prefixes`, so `GB`, `GB/T`, `JB/T`, `T/` … resolve to `Relaton::Gb`. `CN` is not a pubid prefix, so `prefix_flavor("CN")` is `[]`; no caller in this repo used it, and `Db` routing still reads `@prefix`. `HB` resolves to `[Gb, Nist, Bsi]`, pinned in `spec/relaton/prefix_flavor_spec.rb`.
+
+## External dependencies
+
+`cnccs ~> 0.1.1`, `gb-agencies ~> 0.0.1`, `mechanize ~> 2.10`, `csv ~> 3.0`, `relaton-core`, `relaton-iso`.
+
+## Testing
+
+RSpec with WebMock + VCR (cassettes in `spec/vcr_cassettes/`). Network is blocked via WebMock. SimpleCov and equivalent-xml are loaded via `spec/support/`. No index fixture — GB is scraped, not indexed; `spec/fixtures/` holds XML/YAML round-trip data.