metanorma-ietf 3.7.11 → 3.7.12.pre.alpha.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16abd3bccb54974e0c04c25e04bb71e79887b728395927a119922170ad13f3d6
-  data.tar.gz: 79aee453b25eb14b62fc2f7b9842830a07d93f50c8a9b46e731679a1eeaa91f8
+  metadata.gz: 36d6ea8e8fab7b3db968d8ee8132b4aa2791f2e848862889e5d2ebc40d8950df
+  data.tar.gz: b64cae2ed6fe3e8ff272e0ce8f16fe116c63ea73ba9cb318a7ca10e900fe8701
 SHA512:
-  metadata.gz: f054786c9b9b730213d6fd582ed2bed04591d7e78ae60c54214d6f40636cf2c88b9dcf3539d3583667d04d407bad13e3a5e94cc6c1e5e871072d0e367e979d63
-  data.tar.gz: c43c6050cd0de928a77cd0b3ad41f1e9de94d97f31b38c53159011580d92ad52a0fba70dedd4d36573984835e7c3563d4662c2cbdfa9bad7f9550111d2e7a8c6
+  metadata.gz: 3c8ea1d5c55c02f2c28b541364f2f51d8e24c552cb4c00aec22f278fa8da27e12785cddef5165953db4cfb18c8a2b03d92d0071cea725ea580e387edf8c6fdd0
+  data.tar.gz: e5fb2a68c345b21282e3fbd45c78acab783f7d06450fa8209b9bd213b19fd6a31aba332be16587c15fe6474a4249428e76a3b765ea84211fe16e7a785741a24a

data/.gitignore

@@ -8,6 +8,11 @@
 /spec/reports/
 /tmp/
 .tmp.xml
+test.err.html
+test.rfc.xml
+test.xml
+.asciidoc.log.txt
+metanorma.asciidoc.log.txt
 
 # rspec failure tracking
 .rspec_status
@@ -20,5 +25,11 @@
 .rubocop-https--*
 
 /Gemfile.lock
+/Gemfile.devel
 /test.err
 /test.rfc.xml.err
+document.xml
+document.err.html
+document.rfc.xml.err
+*.gem
+spec/relatondb/

data/.html.err.html

@@ -0,0 +1,118 @@
+<html><head><title>./.html.err.html errors</title>
+<meta charset="UTF-8"/>
+<style> pre { white-space: pre-wrap; }
+thead th { font-weight: bold; background-color: aqua; }
+.severity0 { font-weight: bold; background-color: lightpink }
+.severity1 { font-weight: bold; }
+.severity2 { }
+.severity3 { font-style: italic; color: grey; }
+</style>
+</head><body><h1>./.html.err.html errors</h1>
+<ul><li><p><b><a href="#Relaton">Relaton</a></b>: Severity 3: <b>1</b> error</p></li>
+
+<li><p><b><a href="#Style">Style</a></b>: Severity 2: <b>2</b> errors</p></li>
+
+<li><p><b><a href="#Metanorma_XML_Syntax">Metanorma XML Syntax</a></b>: Severity 2: <b>22</b> errors</p></li>
+</ul>
+<h2 id="Relaton">Relaton</h2>
+<table border="1">
+<thead><th width="5%">Line</th><th width="20%">ID</th><th width="10%">Error</th>
+<th width="20%">Message</th><th width="40%">Context</th><th width="5%">Severity</th></thead>
+<tbody>
+<tr class="severity3">
+<td></td><th><code>ISO/IEC 10118-3</code></th><td>RELATON_4</td>
+<td>(Error from Relaton) not found in cache, if you wish to ignore cache please use <code>no-cache</code> option.</td><td><pre></pre></td><td>3</td></tr>
+</tbody></table>
+<h2 id="Style">Style</h2>
+<table border="1">
+<thead><th width="5%">Line</th><th width="20%">ID</th><th width="10%">Error</th>
+<th width="20%">Message</th><th width="40%">Context</th><th width="5%">Severity</th></thead>
+<tbody>
+<tr class="severity2">
+<td>000433</td><th><code><a href='./.html.html#frame'>frame</a></code></th><td>STANDOC_48</td>
+<td>(generic warning) Hanging paragraph in clause</td><td><pre>&lt;clause id=&quot;_7db07fdc-fcc6-b1d5-fbd9-4af3fe5d67d4&quot; anchor=&quot;frame&quot; inline-header=&quot;false&quot; obligation=&quot;normative&quot;&gt;
+&lt;title id=&quot;_7f507f76-d16f-6909-7c72-3bf386b1aac3&quot;&gt;Frame Format&lt;/title&gt;
+&lt;p id=&quot;_e5b93d18-9b70-055e-f3ea-e7d3e221cb31&quot;&gt;The IP &lt;em&gt;datagram&lt;/em&gt; is &lt;strong&gt;printed&lt;/strong&gt;, on a small scroll of paper, in hexadecimal, with each octet separated by whitestuff and blackstuff. The scroll of paper is wrapped around one leg of the avian carrier. A band of duct tape is used to secure the datagram&apos;s edges.  The bandwidth is limited to the leg length.  The MTU is variable, and paradoxically, generally increases with increased carrier age.  A typical MTU is 256 milligrams.  Some datagram padding may be needed.&lt;eref type=&quot;inline&quot; bibitemid=&quot;RFC7253&quot; citeas=&quot;RFC 7253&quot;&gt; &lt;display-text&gt;alt&lt;/display-text&gt; &lt;/eref&gt; &lt;/p&gt;
+
+&lt;p id=&quot;_cbfa7d28-50f5-f4d4-8920-3ff81bb853de&quot;&gt;Upon receipt, the duct tape is removed and the paper copy of the datagram is optically scanned into a electronically transmittable form.&lt;eref type=&quot;inline&quot; bibitemid=&quot;RFC7253&quot; citeas=&quot;RFC 7253&quot;/&gt; &lt;/p&gt;</pre></td><td>2</td></tr>
+<tr class="severity2">
+<td>000468</td><th><code><a href='./.html.html#_b1474689-968c-d908-ec3c-52106a8e875b'>_b1474689-968c-d908-ec3c-52106a8e875b</a></code></th><td>STANDOC_48</td>
+<td>(generic warning) Hanging paragraph in clause</td><td><pre>&lt;clause id=&quot;_b1474689-968c-d908-ec3c-52106a8e875b&quot; inline-header=&quot;false&quot; obligation=&quot;normative&quot;&gt;
+&lt;title id=&quot;_0615fb18-bab7-fcce-7fe6-b06f78cdb707&quot;&gt;Definitions&lt;/title&gt;
+&lt;dl id=&quot;_188c1a32-874f-ef99-a4e5-24156e77be2b&quot;&gt; &lt;dt&gt;OSCCA-compliant:&lt;/dt&gt;
+&lt;dd id=&quot;_2c9455c4-4da3-7bc6-4086-0552e4f2e2d7&quot;&gt; &lt;p id=&quot;_5adcd946-10f3-f180-1cbb-f92b4fabcca2&quot;&gt;All cryptographic algorithms used are compliant with OSCCA  regulations.&lt;/p&gt;
+&lt;/dd&gt;</pre></td><td>2</td></tr>
+</tbody></table>
+<h2 id="Metanorma_XML_Syntax">Metanorma XML Syntax</h2>
+<table border="1">
+<thead><th width="5%">Line</th><th width="20%">ID</th><th width="10%">Error</th>
+<th width="20%">Message</th><th width="40%">Context</th><th width="5%">Severity</th></thead>
+<tbody>
+<tr class="severity2">
+<td></td><th><code>XML Line 000021:84</code></th><td>STANDOC_7</td>
+<td>text not allowed here; expected the element end-tag or element "draft" or "revision-date"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000082:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000085:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000088:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000091:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000237:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000240:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000243:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000246:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000323:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000326:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000405:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000408:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000411:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000414:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000417:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000424:132</code></th><td>STANDOC_7</td>
+<td>element "pi" not allowed here; expected the element end-tag or element "backpage-image", "coverpage-image", "ics", "index­Include", "innercoverpage-image", "ipr­Extract", "showOnFrontPage", "sort­Refs", "structuredidentifi­er", "sym­Refs", "toc­Depth", "toc­Include" or "tocside-image"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000435:606</code></th><td>STANDOC_7</td>
+<td>element "display-text" not allowed here; expected the element end-tag, text or element "date", "locality" or "localityStack"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000510:6</code></th><td>STANDOC_7</td>
+<td>element "pre" missing required attribute "id"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000648:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000651:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+<tr class="severity2">
+<td></td><th><code>XML Line 000654:13</code></th><td>STANDOC_7</td>
+<td>element "keyword" incomplete; missing required element "taxon"</td><td><pre></pre></td><td>2</td></tr>
+</tbody></table>
+</body></html>

data/.rspec

@@ -1,2 +1 @@
 --color
---require spec_helper

data/Gemfile

@@ -1,9 +1,34 @@
-Encoding.default_external = Encoding::UTF_8
-Encoding.default_internal = Encoding::UTF_8
-
 source "https://rubygems.org"
-git_source(:github) { |repo| "https://github.com/#{repo}" }
 
 gemspec
+gem "metanorma-mirror", "~> 1.0", github: "metanorma/metanorma-mirror", branch: "main"
+
+# and the pubid-2 / relaton-bib 2.2 / metanorma-document 0.5 chain.
+# Revert each pin once the corresponding PR merges:
+#   - https://github.com/metanorma/metanorma-document/pull/45
+gem "metanorma-standoc", github: "metanorma/metanorma-standoc", branch: "main"
+gem "metanorma-document", github: "metanorma/metanorma-document", branch: "main"
+gem "isodoc", github: "metanorma/isodoc", branch: "main" # merged as #825
+gem "pubid", "~> 2.0.0.pre.alpha"
+
+gem "canon"
+gem "equivalent-xml"
+gem "htmlentities"
+gem "metanorma", github: "metanorma/metanorma", branch: "main"
+gem "rake"
+# Gemfile.devel may pin relaton-bib to a git branch (declaring the
+# same gem twice aborts the rescued eval_gemfile silently)
+gem "relaton-bib", "~>2.1" unless File.exist?(File.join(__dir__, "Gemfile.devel"))
+gem "rspec"
+gem "rubocop"
+gem "rubocop-performance"
+gem "simplecov"
+gem "timecop"
+gem "webmock"
 
 eval_gemfile("Gemfile.devel") rescue nil
+
+gem "metanorma-iso", github: "metanorma/metanorma-iso", branch: "main"
+gem "metanorma-core", github: "metanorma/metanorma-core", branch: "main"
+# leptris 1.9.359+ drops Declaration#to_xml and changes the validator
+# surface (leptris#1733); pin the 1.9.356-era pair until leptris ships

data/Gemfile.devel

@@ -0,0 +1 @@
+gem "relaton-bib", github: "relaton/relaton-bib", branch: "feat/rfcxml-v3-export"

data/TODO.rfc-to-from-conversions/01-fix-reference-anchor-uuid.md

@@ -0,0 +1,18 @@
+# Task 1: Fix bibliography reference anchors using UUIDs instead of original IDs
+
+## Problem
+When forward-transforming ADOC input with `[bibliography] == References * [[[RFC2119,Key Words]]] ...`, the reference anchor in RFC XML output is a UUID like `_302856a2-5468-3783-9d82-c075e1073e0b` instead of the expected `RFC2119`. This causes xml2rfc to emit:
+```
+Warning: Unused reference: There seems to be no reference to [_302856a2-...]
+```
+
+## Root Cause
+The forward transformer's reference_transformer.rb likely doesn't extract the original `id` or anchor from the `<bibitem id="RFC2119">` element in semantic XML, instead generating a new UUID.
+
+## Fix Location
+`lib/metanorma/ietf/transformer/reference_transformer.rb` — the `transform_bibitem` or equivalent method that creates `<reference>` elements must use the bibitem's `id` attribute as the RFC XML `anchor`.
+
+## Verification
+- Run the full ADOC integration spec
+- xml2rfc should have 0 warnings about unused references
+- The `<reference anchor="RFC2119">` should appear in RFC XML output

data/TODO.rfc-to-from-conversions/02-fix-extract-paragraph-text.md

@@ -0,0 +1,13 @@
+# Task 2: Fix extract_paragraph_text to use `text` attribute (not `content`)
+
+## Problem
+`extract_paragraph_text` in `inline_transformer.rb` calls `paragraph.content` but `ParagraphBlock` has no `content` attribute — it uses `text` (a string collection). This causes `NoMethodError` when forward-transforming MN XML that was produced by the reverse transformer (round-trip scenario).
+
+## Root Cause
+`ParagraphBlock` (from metanorma-document) maps `<p>` content to the `text` attribute (collection). The `content` attribute only exists on some other model types. The forward transformer was checking `content` first, which triggers lutaml-model's `method_missing` and raises.
+
+## Fix Location
+`lib/metanorma/ietf/transformer/inline_transformer.rb` — `extract_paragraph_text` method. Already partially fixed to use `paragraph.text`, but need to verify it's complete and no other callers depend on `content`.
+
+## Status
+Partially done — method was updated. Need to verify all callers work.

data/TODO.rfc-to-from-conversions/03-fix-duplicate-anchors-roundtrip.md

@@ -0,0 +1,26 @@
+# Task 3: Fix duplicate anchors and invalid anchor attributes in round-trip RFC XML
+
+## Problem
+When round-tripping (RFC XML → reverse → forward → RFC XML), the output has:
+1. **Duplicate anchors** — same UUID appearing on multiple elements (e.g., `_d36058ae...` on multiple `<t>` elements)
+2. **Invalid `anchor` on `<t>`** — RFC XML v3 `<t>` element does NOT support `anchor` attribute, but the forward transformer is generating `<t anchor="...">` 
+
+xml2rfc errors:
+```
+Error: Invalid attribute anchor for element t, at /rfc/middle/section[1]/t[5]
+Error: Duplicate xsd:ID attribute anchor="_d36058ae-..." found.
+```
+
+## Root Cause
+The forward transformer's `transform_paragraph` (or `transform_t`) sets `anchor` on `<t>` elements. In RFC XML v3, only `<section>`, `<figure>`, `<table>`, `<ul>`, `<ol>`, `<references>` etc. support `anchor` — NOT `<t>`.
+
+The duplicate anchors happen because the reverse transformer preserves IDs in the MN XML, and then the forward transformer re-applies those same IDs, but the MN XML model has `id` on `ParagraphBlock` which maps to both the paragraph's `id` AND gets used as an RFC anchor.
+
+## Fix Location
+1. `lib/metanorma/ietf/transformer/block_transformer.rb` — `transform_paragraph` must NOT set `anchor` on `<t>` elements
+2. Check all element types in forward transformer that set `anchor` — verify they only do so for RFC v3 elements that support it
+
+## Verification
+- Round-trip example.xml through forward→reverse→forward→xml2rfc with exit 0 and 0 errors
+- No "Invalid attribute anchor" errors
+- No "Duplicate xsd:ID" warnings

data/TODO.rfc-to-from-conversions/04-fix-li-t-children-roundtrip.md

@@ -0,0 +1,22 @@
+# Task 4: Fix `<li>` containing `<t>` children in round-trip
+
+## Problem
+xml2rfc error:
+```
+Error: Element li has extra content: t, at /rfc/middle/section[1]/ul[4]/li[1]/t
+```
+
+In RFC XML v3, `<li>` can contain `<t>` but the xml2rfc error suggests a structural issue. This happens in the round-trip output.
+
+## Root Cause
+The reverse transformer creates paragraph blocks inside list items. When forward-transforming back, those paragraphs become `<t>` inside `<li>`, but the surrounding structure may be wrong — e.g., the `<t>` should be a direct child of `<li>` but there might be extra wrapping, or the `<li>` has mixed content that isn't allowed.
+
+Need to inspect the actual round-trip XML to see the exact structure.
+
+## Fix Location
+- Likely `lib/metanorma/ietf/transformer/list_transformer.rb` — how list items with paragraph children are transformed
+- Possibly `lib/metanorma/ietf/transformer/rfc_v3_to_ietf/list_transformer.rb` — how reverse transformer creates list item content
+
+## Verification
+- Round-trip example.xml → xml2rfc exit 0
+- No "Element li has extra content" errors

data/TODO.rfc-to-from-conversions/05-write-pipeline1-spec.md

@@ -0,0 +1,22 @@
+# Task 5: Write integration spec for Pipeline 1 (ADOC → RFC XML → xml2rfc)
+
+## Goal
+Verify that ADOC documents can be converted to semantic XML, parsed by metanorma-document, transformed to RFC XML v3, and accepted by xml2rfc with **no errors and no warnings**.
+
+## Test Cases
+1. Simple document (title, sections, paragraphs) — clean pass
+2. Full document (abstract, intro, lists, tables, bibliography, BCP14 keywords, notes) — clean pass
+3. Fixture documents (example.xml, antioch.xml) — clean pass
+
+## Assertion Criteria
+- `xml2rfc --text` exit code must be 0
+- No "Error:" lines in xml2rfc output
+- RFC XML must have `<rfc>`, `<front>`, `<middle>`, `<back>`
+- Title, author, sections, metadata preserved correctly
+
+## Current Status
+DONE. Integration spec includes:
+- Step-by-step pipeline tests (ADOC→XML, XML→model, model→RFC XML, RFC XML→xml2rfc)
+- Fixture-based tests with shared examples
+- Content preservation assertions for metadata, sections, lists, tables, BCP14, notes, bibliography
+- 38 integration tests pass, 288 total specs pass with 0 failures

data/TODO.rfc-to-from-conversions/06-write-pipeline2-spec.md

@@ -0,0 +1,27 @@
+# Task 6: Write integration spec for Pipeline 2 (RFC XML → reverse → forward → xml2rfc)
+
+## Goal
+Verify that RFC XML v3 documents can be reverse-transformed to metanorma-document, then forward-transformed back to RFC XML v3, and the round-tripped RFC XML is accepted by xml2rfc with **no errors and no warnings**.
+
+## Test Cases
+1. Simple RFC XML (sections, paragraphs, lists, bibliography) — clean round-trip
+2. Complex RFC XML (example.xml fixture forward output) — clean round-trip
+3. Antioch.xml fixture forward output — clean round-trip
+
+## Assertion Criteria
+- `xml2rfc --text` on round-tripped RFC XML exit code must be 0
+- No "Error:" lines
+- No "Warning:" lines
+- Round-tripped RFC XML must preserve: title, author, sections, references
+- Content text must be preserved (no data loss)
+
+## Prerequisites
+- Task 2 (fix extract_paragraph_text) — DONE
+- Task 3 (fix duplicate anchors) — DONE
+- Task 4 (fix li/t children) — DONE
+
+## Current Status
+DONE. Integration spec includes:
+- Shared examples for fixture-based round-trip (example.xml, antioch.xml)
+- ADOC-based full round-trip test (ADOC → RFC → reverse → forward → xml2rfc)
+- All 38 integration tests pass, 288 total specs pass with 0 failures

data/TODO.rfc-to-from-conversions/07-final-verification.md

@@ -0,0 +1,14 @@
+# Task 7: Final verification — all specs pass
+
+## Goal
+Ensure all 275+ specs pass with 0 failures after all fixes.
+
+## Steps
+1. Run `bin/rspec` — all specs green
+2. Run `bin/rspec spec/transformer/` — all transformer specs green
+3. Run `bin/rspec spec/transformer/integration_spec.rb` — all integration specs green
+4. Run rubocop if needed
+
+## Acceptance Criteria
+- `bin/rspec` returns 0 failures
+- No regressions in existing specs

data/TODO.rfc-to-from-conversions/bugreport-metanorma-document-circular-autoload.md

@@ -0,0 +1,112 @@
+# Bug Report: Circular Autoload Dependency in Register Setup
+
+**Severity:** High — prevents any non-ISO flavor from loading via `require "metanorma/document"`
+
+**Affected file:** `lib/metanorma/registers/setup.rb` lines 14–15
+
+## Description
+
+`registers/setup.rb` defines module-level constants that trigger autoloads before the `Setup` module's methods are fully defined:
+
+```ruby
+module Metanorma
+  module Registers
+    module Setup
+      SD = Metanorma::StandardDocument   # line 14 — triggers autoload of standard_document
+      ISO = Metanorma::IsoDocument       # line 15 — triggers autoload of iso_document
+
+      class << self
+        def setup_iso_register            # line 21 — not yet defined when line 15 autoloads iso_document.rb
+          ...
+        end
+      end
+    end
+  end
+end
+```
+
+## How it breaks
+
+1. `ietf_document.rb` line 11 calls `Metanorma::Registers::Setup.setup_ietf_register`
+2. This triggers autoload of `registers/setup.rb`
+3. Line 15: `ISO = Metanorma::IsoDocument` triggers autoload of `iso_document.rb`
+4. `iso_document.rb` line 16: `Metanorma::Registers::Setup.setup_iso_register`
+5. But `setup_iso_register` isn't defined yet — the `class << self` block hasn't been evaluated (still at line 15)
+6. **`NoMethodError: undefined method 'setup_iso_register'`**
+
+## Symmetric problem
+
+Every `*_document.rb` file calls `Registers::Setup.setup_*_register` at load time. Any two flavors that are both referenced inside `setup.rb` will have this circular dependency. For example, if a new flavor's register setup references `Metanorma::IeeeDocument`, loading `ieee_document.rb` would trigger `setup.rb` which references `IsoDocument`, which calls `setup_iso_register` before it's defined.
+
+## Current workaround
+
+metanorma-ietf forces the loading order in its transformer.rb:
+
+```ruby
+require "metanorma/document"
+
+# Force-load order to break the circular autoload
+Metanorma::StandardDocument::Sections
+Metanorma::IsoDocument::Sections
+```
+
+This pre-resolves `Metanorma::IsoDocument` before `ietf_document.rb` references `Registers::Setup`, so when `setup.rb` loads, `ISO = Metanorma::IsoDocument` resolves without triggering a new autoload.
+
+## Suggested fix
+
+Move the module-level constants inside the methods that use them, or lazy-initialize them:
+
+```ruby
+module Metanorma
+  module Registers
+    module Setup
+      class << self
+        def setup_iso_register
+          sd = Metanorma::StandardDocument
+          iso = Metanorma::IsoDocument
+          reg = Lutaml::Model::Register.new(:iso_document)
+          Lutaml::Model::GlobalRegister.register(reg)
+
+          reg.register_global_type_substitution(
+            from_type: sd::Sections::ClauseSection,
+            to_type:   iso::Sections::IsoClauseSection,
+          )
+          # ... etc
+        end
+
+        def setup_ietf_register
+          sd = Metanorma::StandardDocument
+          ietf = Metanorma::IetfDocument
+          reg = Lutaml::Model::Register.new(:ietf_document)
+          Lutaml::Model::GlobalRegister.register(reg)
+          # ... etc
+        end
+      end
+    end
+  end
+end
+```
+
+This way, no autoloads are triggered at module-definition time, and the circular dependency is eliminated.
+
+## Secondary issue: IETF content model gaps
+
+While adapting the IETF transformer to the restructured metanorma-document, we found these model gaps. These are **not blockers** (we have workarounds), but they represent model design questions for the metanorma-document team:
+
+### 1. `IetfContentSection` lacks `unnumbered` and `toc`
+
+`IetfClauseSection` (extends `ClauseSection`) inherits `unnumbered` and `toc` from its base class. But `IetfContentSection` (extends `ContentSection`) does not have these attributes. In the IETF context, preface content sections can be unnumbered, so the forward transformer needs to check `unnumbered` on content sections too.
+
+**Current workaround:** `rescue NoMethodError` guards in the forward transformer.
+
+### 2. No IETF-specific term types
+
+The `StandardDocument` base provides `Term`, `TermsSection`, `TermDefinition`, `TermExpression`, `TermNameElement`, and `Designation`. But IETF documents that include terminology need these same types. The reverse transformer uses `StandardDocument` base types instead of `IsoDocument` types (which is correct per the architecture), but there's no IETF-specific customization layer.
+
+**Status:** Working with `StandardDocument` base types. No IETF-specific term model needed yet, but the metanorma-document team should be aware that IETF may need term model extensions in the future.
+
+### 3. `Preface.content` type is `ContentSection`
+
+The `Preface` model's `content` attribute is typed as `ContentSection`, which maps `"clause" → :subsection`. But some flavors (like IETF) put clause-like content in preface `content`. The register substitution `ContentSection → IetfContentSection` applies to all content items, including objects that behave more like `ClauseSection`. This causes attribute mismatch during serialization.
+
+**Current workaround:** The reverse transformer creates `IetfContentSection` instances for preface content, which serializes correctly. But if richer clause features (amend, terms, definitions) are needed in preface content, the type system needs a more flexible approach.

data/TODO.transform-bidirectional/01-bidirectional-architecture.md

@@ -0,0 +1,86 @@
+# 01: Bidirectional Transformer Architecture
+
+## Problem
+
+The current transformer is one-directional: `IetfToRfcV3` only handles Metanorma XML → RFC XML v3. There is no reverse transformer. The architecture is a single monolithic class with 13 mixins, ~4,400 lines total, using private APIs and XML string manipulation.
+
+## Design
+
+### 1. Introduce `Transform` protocol module
+
+Define a `Transform` module that both directions implement:
+
+```ruby
+module Metanorma::Ietf::Transformer
+  module Transform
+    # @param input [String] XML string
+    # @param options [Hash] transformation options
+    # @return [String] transformed XML string
+    def self.call(input, options = {})
+      raise NotImplementedError
+    end
+  end
+end
+```
+
+### 2. Split into two transformer classes under a common base
+
+```
+lib/metanorma/ietf/transformer/
+  base.rb                    # Shared utilities (ls_text, to_ncname, etc.)
+  ietf_to_rfc_v3.rb          # Forward: Metanorma XML → RFC XML v3 (refactored)
+  rfc_v3_to_ietf.rb          # Reverse: RFC XML v3 → Metanorma XML (NEW)
+```
+
+`Base` holds:
+- `ls_text`, `extract_text`, `escape_xml_text`, `to_ncname`, `to_array`, `anchor_for`
+- `build_organization` (shared between forward and reverse)
+- No state (no `@doc`, `@xrefs`, etc.) — those belong to the concrete transformers
+
+### 3. Refactor `IetfToRfcV3` to extend `Base`
+
+Move shared helpers to `Base`. Keep the 13 existing modules but:
+- Each module becomes a standalone class or remains a mixin — but no more `send` to private lutaml-model APIs
+- Replace `NullBibdata`/`NullExt` with proper null objects (see TODO 04)
+
+### 4. Create `RfcV3ToIetf` (reverse transformer)
+
+New class extending `Base` with its own modules:
+- `RfcV3ToIetf::Metadata` — RFC attributes → bibdata
+- `RfcV3ToIetf::Front` — `<front>` → Metanorma front matter
+- `RfcV3ToIetf::Section` — `<middle>`/`<back>` → Metanorma sections
+- `RfcV3ToIetf::Block` — paragraphs, sourcecode, etc.
+- `RfcV3ToIetf::Inline` — xref, eref, cref, etc.
+- `RfcV3ToIetf::Table` — tables
+- `RfcV3ToIetf::Figure` — figures/artwork
+- `RfcV3ToIetf::List` — lists
+- `RfcV3ToIetf::Term` — terms/definitions
+- `RfcV3ToIetf::Reference` — bibliography
+- `RfcV3ToIetf::Cleanup` — post-processing
+
+### 5. Update entry point
+
+```ruby
+module Metanorma::Ietf::Transformer
+  def self.convert(xml_string, direction: :forward, options = {})
+    case direction
+    when :forward then Forward.call(xml_string, options)
+    when :reverse then Reverse.call(xml_string, options)
+    end
+  end
+end
+```
+
+## Files to modify/create
+
+| File | Action |
+|------|--------|
+| `lib/metanorma/ietf/transformer/base.rb` | NEW — shared utilities |
+| `lib/metanorma/ietf/transformer/ietf_to_rfc_v3.rb` | Refactor to extend Base |
+| `lib/metanorma/ietf/transformer/rfc_v3_to_ietf.rb` | NEW — reverse transformer |
+| `lib/metanorma/ietf/transformer.rb` | Update entry point with direction parameter |
+
+## Dependencies
+
+- TODO 02 (private API encapsulation) must be done first
+- TODO 04 (NullBibdata replacement) should be done before refactoring