sts 0.6.6 → 0.6.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 201840881c86c036233c5bb1305bf176bbe6bf4ca0f43a22e370105cac0ed54f
-  data.tar.gz: 5845dd5fb849611a4a11bf173af68b3c226cf5c807d09bb721cf09cecdc8544b
+  metadata.gz: cd02c307a6e1d5f238e8e05db78958bf73d1bc05c98c170ad89005fb205c7e88
+  data.tar.gz: 0bc64d38cf7f5ffd0151db213b9cc99dd25ca979b9eacabf0fb5b7f78b4b19af
 SHA512:
-  metadata.gz: 20d4010381ed9daf225ecf13afc922b5cf338ec62318b24ee22554163885c815aa5db22257be600262fe8be9f7f8668a0569805e5a201db35b98a84e1fbfa982
-  data.tar.gz: c4078992f02ab4a9e6640e750d2f54b29136b187a58b9e42cc21e9a2cc76b7049c6e25f9b823e0827f2851468e3f0dcc618271526880ae3121be3f2fc5512d69
+  metadata.gz: 421983c008de22adbe0ca5b7e101590d1a025b76582acb6c750d4d7ebad8582abd9bfa12386ed119d11e9ac2e5ccfe6d6f1216f991ce457fc18e98dd5a86ed91
+  data.tar.gz: d0d7b00dbd0c8c53268c561fdb965228e753f90c7cc52c0c9c3fa842ba22d4a105232a2b0b0bec778387e86e1c76e6fd3f95e6bad3f1593e5c566e126f3d8b42

data/TODO.roadmap/00-overview.md

@@ -0,0 +1,85 @@
+# sts-ruby + lutaml-model Roadmap
+
+**Date**: 2026-07-27
+**Replaces**: `TODO.sts-refactor/00-overview.md` (now mostly historical — that
+series landed through PRs #31, #40 work, #42, #44–#50). This roadmap covers
+all remaining work across both repos.
+
+## Status at start (2026-07-27)
+
+- **sts gem**: 0.6.6 on RubyGems
+- **Issue #40**: 11 IsoSts→NisoSts refs remaining (5 recursive roots +
+  4 child-bearing roots + 2 already-enumerated ArticleTitle / ElementCitation
+  co-roots)
+- **Open PRs/Issues**: #40 (umbrella)
+- **Anti-pattern enforcement**: 9 per-file checks in
+  `spec/anti_patterns_spec.rb`; covers all global rules
+- **Tests**: 2563 examples, 0 failures
+
+## Tracks
+
+Work is grouped into four MECE tracks. Each track is independent unless
+noted.
+
+| Track | Subject | Items |
+|---|---|---|
+| A | lutaml-model upstream analysis (filed as robustness suggestions) | 02 |
+| B | Issue #40 namespace coupling completion | 01 (done), 03 (done), 04 |
+| C | Architectural improvements (DRY, versioning, audit) | 05, 07, 08 |
+| D | Quality, specs, and coverage | 09, 10, 11 |
+
+## Priority order
+
+The priority is "highest leverage per unit of risk" first:
+
+1. **B.01** (MathmlNamespace deduplication): DONE 2026-07-27. sts-ruby had
+   two Ruby classes for one XML namespace; deleted one, use `Mml::Namespace`
+   directly. Originally misdiagnosed as a lutaml-model bug — see
+   `01-mathml-namespace-deduplication.md` for the lesson.
+2. **B.03** (child-bearing roots): DONE 2026-07-27. Modelled License,
+   TermHead, CustomMetaGroup closures. Closed 5 of 11 issue #40 refs.
+3. **A.02** (lutaml-model ElementBuilder dispatch): filed as
+   `BUGREPORT.element-builder-dispatch-on-value-class.md` in lutaml-model.
+   Pure documentation; zero risk. **Reframed as a robustness suggestion,
+   not a bug** — sts-ruby's responsibility to use correct types was the
+   actual fix (PR #47 deleted duplicate Fn classes).
+4. **C.07** (TbxIsoTml misclassification audit): documents a deferred audit
+   (Xref, TableWrap, etc.) — pattern is already proven by Fn/FnGroup and
+   Math removals.
+5. **C.05** (Content MathML unification): 148 parallel classes in
+   `lib/sts/niso_sts/mml_content/` — same DRY argument as Presentation
+   MathML unification (commit 9e977a5).
+6. **B.04** (recursive roots): the heavy lift. Each root pulls a ~78-element
+   mutually-recursive core. Requires per-element planning. Most architecturally
+   significant.
+7. **C.08** (register versioning): lets ISOSTS v1.1, NISO STS 1.0, NISO STS 1.2
+   coexist without class-name clashes.
+8. **D.09, D.10, D.11** (quality, coverage, docs): ongoing.
+
+## Architectural principles (enforced on all new work)
+
+- **MECE**: each model class lives in exactly one namespace; no parallel
+  hierarchies across namespaces.
+- **Model-driven**: every XML element reference is a typed
+  `attribute :foo, ::Sts::<Namespace>::Foo`. No runtime string lookup.
+- **Open/Closed**: adding a new STS host namespace = adding a new Foo class
+  there, not editing existing namespaces.
+- **DRY**: one class per (namespace, XML element) pair. Shared attribute
+  patterns within a namespace use Ruby modules (not cross-namespace base
+  classes — those are forbidden by the 2026-05-07 ADR).
+- **No anti-patterns**: no `send`, no `instance_variable_set/get`, no
+  `respond_to?` type-checks, no `require_relative` in lib/ (autoload only),
+  no `require` with internal library paths. Enforced by
+  `spec/anti_patterns_spec.rb`.
+- **Autoload convention**: top-level `lib/sts.rb` autoloads namespaces;
+  `lib/sts/<namespace>.rb` autoloads classes. Alphabetical within category
+  groups.
+
+## Memory cross-references
+
+- [[architecture-namespace-independence]] — IsoSts/NisoSts never share base types
+- [[duplicate-fn-class-attribute-mismatch]] — the trap A.02 prevents
+- [[isosts-uses-mathml2-not-mathml3]] — V2/V3 host binding pattern
+- [[mml-gem-integration-failure]] — MathmlNamespace duplication context
+- [[release-workflow-two-phase]] — release flow
+- [[ci-rubocop-stricter-than-local]] — substring-check convention

data/TODO.roadmap/01-mathml-namespace-deduplication.md

@@ -0,0 +1,62 @@
+# 01: MathmlNamespace deduplication (DONE)
+
+**Status**: complete (2026-07-27).
+**Originally tracked as**: `01-lutaml-model-namespace-scope-uri-matching.md`
+(misdiagnosed as a lutaml-model bug) and `06-mathml-namespace-deduplication.md`
+(blocked on the misdiagnosed upstream fix). Merged and completed here.
+
+## Original misdiagnosis
+
+When sts-ruby unified Presentation MathML on the mml gem (commit 9e977a5),
+the `mml:` prefix was dropped on serialization unless both
+`Sts::Namespaces::MathmlNamespace` AND `Mml::Namespace` were listed in
+`IsoSts::Standard#namespace_scope` / `NisoSts::Standard#namespace_scope`.
+
+The initial diagnosis (filed as `BUGREPORT.namespace-scope-uri-matching.md`
+in lutaml-model) blamed `namespace_scope` for matching by class identity
+instead of URI. The proposed fix was to change lutaml-model's matching
+semantics.
+
+## Actual root cause
+
+**sts-ruby had two Ruby classes for one XML namespace.** A namespace IS
+its URI (per Namespaces in XML 1.0). `Sts::Namespaces::MathmlNamespace`
+and `Mml::Namespace` both declared:
+
+```ruby
+uri "http://www.w3.org/1998/Math/MathML"
+prefix_default "mml"
+```
+
+They were the same namespace. The duplication was the smell; the
+"workaround" of listing both was actually papering over the duplication.
+
+The BUGREPORT was retracted. The fix is purely sts-ruby's responsibility.
+
+## Fix shipped (2026-07-27)
+
+- Deleted `Sts::Namespaces::MathmlNamespace` from `lib/sts/namespaces.rb`.
+- Replaced `::Sts::Namespaces::MathmlNamespace` with `::Mml::Namespace` in:
+  - `lib/sts/iso_sts/standard.rb`
+  - `lib/sts/niso_sts/standard.rb`
+  - `lib/sts/niso_sts/mml_content.rb` (the Content MathML module — still
+    scheduled for unification per TODO.roadmap/05)
+- Added 4 regression specs asserting `MathmlNamespace` is undefined and
+  `Mml::Namespace` is used directly.
+
+## Verification
+
+- 5153 examples, 0 failures.
+- TBX fixture round-trip preserves `<mml:math>` prefix.
+- NISO STS fixture round-trip preserves `<mml:math>` prefix.
+- `grep -rn "MathmlNamespace" lib/` returns nothing.
+
+## Lesson
+
+When you see a "framework limitation" that requires you to declare
+something twice, the more likely explanation is that you have two
+definitions of the same thing. Namespaces in particular are URI-identified;
+two classes for one URI is a DRY violation, not a framework bug.
+
+Memory updated: `mml-gem-integration-failure` no longer describes the
+`namespace_scope` duplication as a "known smell" — it's resolved.

data/TODO.roadmap/02-lutaml-model-element-builder-dispatch.md

@@ -0,0 +1,115 @@
+# A.02: lutaml-model `ElementBuilder` dispatch on `value.class`
+
+**Status**: BUGREPORT drafted; analysis complete. Deferred per downstream
+maintainer feedback (2026-07-25) — see "Why deferred" below.
+**Repo**: `lutaml/lutaml-model`
+**Estimated effort**: small (lutaml-model: ~10 lines + spec)
+
+## Problem
+
+`Lutaml::Xml::TransformationSupport::ElementBuilder#create_nested_model_element`
+(lib/lutaml/xml/transformation/element_builder.rb:131) reuses the rule's
+cached `child_transformation` for serialization regardless of the value's
+actual class. When a caller assigns a `Lutaml::Model::Serializable` whose
+class differs from the declared `attribute_type`, the wrong transformation
+is applied silently:
+
+- The declared type's `compiled_rules` are iterated
+- `extract_rule_value` (rule_applier.rb:252) calls
+  `model_instance.public_send(rule.attribute_name)` on the value
+- If the value's class doesn't have that attribute name (e.g., declared type
+  uses `:paragraph`, value's class uses `:p`), it raises `NoMethodError`
+
+The cache itself is correct: `TransformationRegistry#transformation_key`
+(lib/lutaml/model/transformation_registry.rb:218) includes `object_id`, so
+keys are unique per class. The bug is in the dispatch logic, not the cache.
+
+## Real-world trigger
+
+The original sts-ruby report (PR #47): `Sts::TbxIsoTml::Fn` (Ruby attr
+`:p`) was nested inside `Sts::NisoSts::Back` (whose `:fn_group` is typed
+`NisoSts::FnGroup`, whose `:fn` is typed `NisoSts::Fn` with attr
+`:paragraph`). lutaml-model applied the cached
+`NisoSts::Fn`-transformation to the `TbxIsoTml::Fn` value, calling
+`fn.public_send(:paragraph)` and raising.
+
+## Why deferred
+
+Downstream metanorma-iso maintainer feedback: "introduces a new contract
+that may break other downstream consumers who've been quietly relying on
+the current lenient behavior. Worth doing eventually, but urgency drops
+once #1 lands — without the duplicate classes there's no easy way to
+trigger the trap."
+
+After PR #47 (delete TbxIsoTml::Fn/FnGroup), the trap cannot fire through
+sts-ruby's own classes. The fix is still correct and worth doing, just not
+urgent.
+
+## Proposed lutaml-model fix
+
+In `create_nested_model_element`, dispatch on `value.class` whenever value
+is a `Serializable` that differs from the declared `attribute_type`:
+
+```ruby
+dispatch_on_value_class = union || is_polymorphic ||
+  (value.is_a?(Lutaml::Model::Serialize) &&
+   value.class != rule.attribute_type)
+
+child_transformation = if dispatch_on_value_class
+                         value.class.transformation_for(:xml, register)
+                       else
+                         rule.child_transformation ||
+                           rule.attribute_type.transformation_for(:xml, register)
+                       end
+```
+
+This subsumes the existing `is_polymorphic_subtype` branch (subtypes already
+have `value.class != rule.attribute_type`). The fast path
+(`value.class == rule.attribute_type`) preserves the cached
+`rule.child_transformation` lookup, so no performance regression for the
+common case.
+
+## Files
+
+- `BUGREPORT.element-builder-dispatch-on-value-class.md` in
+  `~/src/lutaml/lutaml-model/`
+- lutaml-model spec: `spec/lutaml/model/cross_class_dispatch_spec.rb` — three
+  examples minimum (unrelated Serializable dispatch, round-trip preserved,
+  declared-type fast path unchanged)
+
+## Verification
+
+- Reproduction case (currently raises in 0.8.18):
+
+  ```ruby
+  class ParentClass < Lutaml::Model::Serializable; end
+  class OtherSerializable < Lutaml::Model::Serializable
+    attribute :name, :string
+    xml do
+      element "other"
+      map_element "name", to: :name
+    end
+  end
+  class Holder < Lutaml::Model::Serializable
+    attribute :child, ParentClass
+    xml do
+      map_element "child", to: :child
+    end
+  end
+
+  h = Holder.new
+  h.child = OtherSerializable.new(name: "x")
+  h.to_xml  # currently: NoMethodError on ParentClass's :name
+  # after fix: serialises using OtherSerializable's mapping
+  ```
+
+## How to apply
+
+1. File BUGREPORT in `~/src/lutaml/lutaml-model/`.
+2. Pair with the existing polymorphic specs (`spec/lutaml/model/polymorphic_spec.rb`)
+   to ensure no regression on subtype dispatch.
+3. Open upstream PR with the fix sketch above.
+
+Revisit when: (a) a second cross-class case emerges anywhere in the
+metanorma fleet, or (b) the next lutaml-model major release (good time to
+tighten contracts).

data/TODO.roadmap/03-issue-40-child-bearing-roots.md

@@ -0,0 +1,57 @@
+# B.03: Issue #40 — model child-bearing IsoSts roots
+
+**Status**: in flight (License, TermHead, CustomMetaGroup all completable in one PR).
+**Blocks**: nothing.
+**Closes**: 5 of 11 IsoSts→NisoSts refs (issue #40).
+
+## Remaining child-bearing refs
+
+| Class | Referenced from | ISOSTS schema complexity |
+|---|---|---|
+| `IsoSts::License` | `IsoSts::Permissions#license` | simple (3 attrs + `<license-p>` children) |
+| `IsoSts::TermHead` | `IsoSts::DefList#term_head` | simple (mixed content) |
+| `IsoSts::CustomMetaGroup` | `IsoSts::{IsoMeta,RegMeta,NatMeta}#custom_meta_group` (×3) | simple (`<custom-meta>` children) |
+
+## Plan
+
+1. **IsoSts::License** — model from ISOSTS.xsd (`<license>` element):
+   - 8 attrs: license_type, specific_use, xml_lang, xlink_* (6)
+   - children: `license_p` (unbounded) — needs `IsoSts::LicenseP` too
+   - `license_p` itself is mixed-content with the full block-element set;
+     for first pass, model `license_p` with content + common inline children
+     (similar to IsoSts::Attrib)
+2. **IsoSts::LicenseP** — needed as License child
+3. **IsoSts::TermHead** — model from ISOSTS.xsd (`<term-head>`):
+   - mixed content
+   - inline-element children (similar to IsoSts::Attrib pattern)
+4. **IsoSts::CustomMetaGroup** — model from ISOSTS.xsd:
+   - No attributes
+   - Single child type: `<custom-meta>` (unbounded)
+5. **IsoSts::CustomMeta** — needed as CustomMetaGroup child
+   - 9 attrs: id, specific_use, xml_lang, xlink_*
+   - children: `<meta-name>`, `<meta-value>`
+6. **IsoSts::MetaName** — `xs:string` element
+7. **IsoSts::MetaValue** — mixed content
+
+## Specs (per established pattern)
+
+- Attribute-set assertions for each new class
+- Child-class type assertions
+- Round-trip test for at least one realistic XML fragment
+- No-NisoSts guard on each new file
+- Repoint type assertions (e.g., `IsoSts::Permissions#license is IsoSts::License`)
+
+## Verification
+
+- `grep -rn "NisoSts::" lib/sts/iso_sts/` count drops from 11 → 6
+- Full test suite green
+- Rubocop clean (anti-patterns spec enforces all rules)
+
+## How to apply
+
+- One PR (e.g., `feat/isosts-license-termhead-custommetagroup`) covering all
+  7 new classes + the 5 repoints.
+- Same pattern as PR #48 (DispQuote/BoxedText) and PR #50 (Attrib): model
+  from ISOSTS.xsd, omit not-yet-modelled IsoSts children, track omissions
+  in the spec comment.
+- Update `TODO.sts-refactor/03-namespace-coupling.md` count.

data/TODO.roadmap/04-issue-40-recursive-roots.md

@@ -0,0 +1,105 @@
+# B.04: Issue #40 — break the recursive roots
+
+**Status**: planning. Heavy lift; needs per-element design.
+**Blocks**: closing issue #40.
+**Closes**: 6 of 11 IsoSts→NisoSts refs (5 recursive roots + ArticleTitle).
+
+## Remaining recursive refs
+
+| Class | Referenced from | Approx. closure size |
+|---|---|---|
+| `IsoSts::ElementCitation` | `IsoSts::Ref#element_citation` | ~78 elements |
+| `IsoSts::PersonGroup` | `IsoSts::MixedCitation#person_group` | ~50 elements |
+| `IsoSts::Collab` | `IsoSts::MixedCitation#collab` | ~40 elements |
+| `IsoSts::Source` | `IsoSts::MixedCitation#source` | ~25 elements |
+| `IsoSts::ArticleTitle` | `IsoSts::MixedCitation#article_title` | ~25 elements |
+| `IsoSts::TermDisplay` | `IsoSts::TermSec#term_display` | ~30 elements |
+
+Each root reaches the same ~78-element mutually-recursive core
+(`sec` → `p` → `disp-quote` → `p`, etc.). The recursion resolves once
+every element in the cycle has an IsoSts class.
+
+## Architecture decision needed
+
+Two strategies, mutually exclusive:
+
+### Strategy A: bottom-up leaf modelling
+
+Model every leaf ISOSTS element (no children) first, then bottom-up
+through the dependency graph. Eventually every recursive cycle has all
+its members as IsoSts classes.
+
+- **Pro**: each PR is small and verifiable
+- **Pro**: every modelled leaf reduces the closure of the recursive roots
+- **Con**: many PRs (could be 50+); requires tracking the dependency DAG
+  in a checklist
+
+### Strategy B: top-down with `raw` mapping
+
+Use lutaml-model's `raw` mapping type to capture the recursive core as
+opaque XML strings, then incrementally model the surface elements.
+
+- **Pro**: closes the recursive refs in fewer PRs
+- **Con**: `raw` mapping doesn't expose the recursive content as Ruby
+  objects — callers can't introspect or modify the captured XML
+- **Con**: violates the model-driven principle for the deferred parts
+
+### Recommendation: Strategy A
+
+Track B.03 (child-bearing roots) closes 5 refs with no recursion.
+Strategy A is the right continuation: model the next layer of leaves
+(elements with no children, or with only already-modelled IsoSts children)
+until the recursive roots' closures collapse.
+
+## Tracking the DAG
+
+A `TODO.roadmap/04-dag.md` (this file's sibling) should list every
+not-yet-modelled ISOSTS element with:
+
+- Element name
+- Whether it has children (and if so, which)
+- Whether all its children are already IsoSts classes
+- Priority (high if it's referenced by a still-NisoSts ref)
+
+This is mechanical work but tedious. A scripted generator from ISOSTS.xsd
+could populate it; the existing `lib/sts/niso_sts/mml_content/` directory
+suggests the project has tolerated generated-model code before.
+
+## Per-root breakdown
+
+### `ElementCitation` (~78 elements)
+
+The biggest. The ISOSTS schema for `<element-citation>` is enormous (37+
+child elements, many recursive). Schema-correct modelling requires:
+- `IsoSts::ElementCitation` itself
+- Many `<name>`, `<date>`, `<page>` style leaves — most already exist as
+  NisoSts classes; need IsoSts equivalents per namespace independence
+- `<person-group>` (also a recursive root — see below)
+
+Likely 10+ PRs to close this root alone.
+
+### `PersonGroup`, `Collab`, `Source`, `ArticleTitle` (~25-50 elements each)
+
+All referenced from `<mixed-citation>`. Each pulls in citation-relevant
+inline content. PersonGroup is itself a minor recursive root (contains
+`<name>` which contains its own structure).
+
+### `TermDisplay` (~30 elements)
+
+Referenced from `<term-sec>`. Pulls in TBX-flavored terminology elements
+plus the regular block-element core.
+
+## Verification
+
+- After each leaf is modelled: `bundle exec rspec` green
+- After each root is closed: `grep -rn "NisoSts::<Root>"` returns nothing
+- After all 6 roots closed: issue #40 down to ~0 refs (only ArticleTitle
+  co-root count check)
+
+## How to apply
+
+- Do B.03 first (closes 5 refs cheaply)
+- Then start B.04 with the smallest root (Source or ArticleTitle)
+- Track DAG progress in `TODO.roadmap/04-dag.md` (sibling file)
+- Each leaf modelled = one PR (same pattern as PRs #48, #50)
+- Cross-reference each PR in `TODO.sts-refactor/03-namespace-coupling.md`

data/TODO.roadmap/05-content-mathml-unification.md

@@ -0,0 +1,75 @@
+# C.05: Content MathML unification on the mml gem
+
+**Status**: planning. Medium-large effort (148 classes to migrate).
+**Depends on**: nothing (independent of A.01, A.02).
+**Memory**: `mml-gem-integration-failure` (Presentation MathML is already
+unified; Content MathML is not).
+
+## Problem
+
+`lib/sts/niso_sts/mml_content/` ships 148 Content MathML classes (Apply,
+Bind, Ci, Cn, Plus, Eq, Lambda, etc.) as a parallel in-gem implementation.
+The mml gem has its own Content MathML set under `Mml::V2::*` and
+`Mml::V3::*` (same pattern as the Presentation MathML it already provides,
+which we unified in commit 9e977a5).
+
+The duplication means:
+- Two implementations of every Content MathML element
+- Attribute sets can drift between them (no schema sync)
+- sts-ruby users get sts-specific behavior, not mml-gem-correct behavior
+- Bug fixes have to land in both repos
+
+## Plan
+
+Same pattern as commit 9e977a5 (which deleted `TbxIsoTml::{Math, Mrow, Mi,
+…}` and replaced with `Mml::V2::Math` / `Mml::V3::Math`):
+
+1. **Inventory** — `ls lib/sts/niso_sts/mml_content/` to enumerate the 148
+   classes (already autoloaded in `lib/sts/niso_sts/mml_content.rb`).
+2. **Verify mml gem coverage** — for each sts class, confirm the mml gem
+   has an equivalent (under `Mml::V2::*` and/or `Mml::V3::*`).
+3. **Repoint** — every `Sts::NisoSts::MmlContent::*` reference becomes
+   `Mml::V2::*` (for ISOSTS-hosted documents) or `Mml::V3::*` (for NISO STS).
+   Follow the host-binding pattern established in PR #45.
+4. **Delete** — once all references are repointed, delete
+   `lib/sts/niso_sts/mml_content/` entirely (and its autoload block).
+5. **Spec** — round-trip tests for documents with Content MathML must
+   continue to pass.
+
+## Risks
+
+- **Coverage gap**: if the mml gem lacks a class for some sts Content
+  element, the migration is blocked. Mitigation: contribute the missing
+  class to the mml gem first.
+- **Attribute divergence**: sts Content classes may have attributes the
+  mml gem lacks (or vice versa). Schema authority is `mathml3.xsd` (NISO
+  STS host) or `ncbi-mathml2/content/*.xsd` (ISOSTS host).
+- **MathML version**: same V2/V3 split as Presentation MathML. sts Content
+  classes are version-agnostic; the mml gem's are not. Migration must
+  preserve the host-binding pattern.
+
+## Files affected
+
+- `lib/sts/niso_sts/mml_content.rb` (the autoload block; will be deleted)
+- `lib/sts/niso_sts/mml_content/*.rb` (~30 files, 148 classes total via
+  grouping files like `operators.rb`, `relations.rb`, `containers.rb`)
+- Any `NisoSts::*` class that references `MmlContent::*` (audit with
+  `grep -rn "MmlContent::" lib/`)
+- `lib/sts/namespaces.rb` — `MathmlNamespace` (relevant if A.01 hasn't
+  landed; the cleanup in C.06 may run before this)
+
+## How to apply
+
+- Read [[isosts-uses-mathml2-not-mathml3]] for the host-binding pattern
+- Read [[mml-gem-integration-failure]] for why the analogous Presentation
+  MathML unification took two attempts
+- Open as a series of PRs (one per mml_content subdirectory) rather than
+  one giant PR; each PR closes one grouping file
+- Final PR deletes the directory and the autoload block
+
+## Verification
+
+- `bundle exec rspec spec/round_trip/reference_docs_spec.rb` — all
+  reference docs with Content MathML still round-trip
+- `grep -rn "MmlContent::" lib/` returns nothing after the final PR
+- Rubocop clean

data/TODO.roadmap/07-tbxisotml-misclassification-audit.md

@@ -0,0 +1,82 @@
+# C.07: TbxIsoTml misclassification audit
+
+**Status**: deferred. Same pattern as the prior Fn/FnGroup (PR #47) and
+Math (commit 9e977a5) removals — proven approach.
+**Memory**: `architecture-namespace-independence` (TbxIsoTml is a shared
+namespace, but only for elements that are *actually* TBX-ISO-TML).
+
+## Problem
+
+`Sts::TbxIsoTml::*` is the namespace for elements defined by ISO 30042
+(TBX-ISO-TML). The standard defines terminology structures: `<termEntry>`,
+`<tig>`, `<term>`, `<descrip>`, `<descripGrp>`, `<note>`, `<definition>`,
+`<source>`, `<langSet>`, `<subjectField>`, `<partOfSpeech>`,
+`<entailedTerm>`, etc.
+
+The current `lib/sts/tbx_iso_tml/` also contains elements that are **not**
+defined by TBX-ISO-TML — they're JATS / NISO STS elements borrowed into TBX
+contexts. These are misclassifications: they should live in the host
+namespace (NisoSts or IsoSts), not TbxIsoTml.
+
+## Suspects (likely misclassifications)
+
+Each was identified by cross-referencing the TBX-ISO-TML (ISO 30042)
+element list. Anything NOT in TBX-ISO-TML is a misfit.
+
+| Class | Actual element source | Should move to |
+|---|---|---|
+| `TbxIsoTml::Xref` | JATS `<xref>` | (already shared via TbxIsoTml per Bold/Italic precedent — but the precedent itself may be wrong) |
+| `TbxIsoTml::TableWrap` | JATS `<table-wrap>` | (same) |
+| `TbxIsoTml::Table`, `Thead`, `Tbody`, `Tfoot`, `Tr`, `Th`, `Td`, `Col`, `Colgroup` | XHTML table model | IsoSts already has equivalents; NisoSts has equivalents |
+| `TbxIsoTml::Caption` | JATS `<caption>` | (same) |
+| `TbxIsoTml::TableWrapFoot` | JATS `<table-wrap-foot>` | (same) |
+| `TbxIsoTml::TableBreak` | JATS extension | (same) |
+| `TbxIsoTml::ExternalGraphic` | JATS `<external-graphic>` | (same) |
+| `TbxIsoTml::ExternalSource` | JATS extension | (same) |
+| `TbxIsoTml::Example` | JATS `<example>` (or NISO STS `<non-normative-example>`) | IsoSts has `NonNormativeExample` |
+| `TbxIsoTml::Fn` ❌ | already removed (PR #47) | — |
+| `TbxIsoTml::FnGroup` ❌ | already removed (PR #47) | — |
+| `TbxIsoTml::Math`, `Mrow`, `Mi`, etc. ❌ | already removed (9e977a5) | — |
+| `TbxIsoTml::Sup`, `TbxIsoTml::Bold`, `TbxIsoTml::Italic` | JATS emphasis group | IsoSts and NisoSts each have equivalents |
+
+## Per-element decision matrix
+
+For each suspect:
+
+1. Confirm the element is NOT in TBX-ISO-TML (ISO 30042 spec lookup).
+2. Identify all call sites (`grep -rn "TbxIsoTml::<Class>" lib/`).
+3. Decide:
+   - **Delete and repoint** — if the host-equivalent class already exists
+     and has compatible API (like Fn → IsoSts::Fn + NisoSts::Fn).
+   - **Promote** — if no host-equivalent exists, create one in each host
+     namespace (parallel class per the ADR 2026-05-07).
+   - **Keep** — if the element genuinely belongs in shared TBX (rare; only
+     for true TBX-ISO-TML elements like `TermEntry`, `Term`, `Tig`).
+
+## Why this matters
+
+Each misclassified class is a potential version-mismatch footgun (same
+trap as the deleted `TbxIsoTml::Fn`). They also blur the architectural
+boundary between TBX (shared, frozen) and STS host namespaces
+(independent, evolving).
+
+## How to apply
+
+- Same pattern as PR #47 (delete TbxIsoTml::Fn/FnGroup)
+- One PR per element family (e.g., one PR for the XHTML table model, one
+  for emphasis, etc.) — keeps review tractable
+- Each PR must update all call sites and add specs asserting the
+  TbxIsoTml class stays deleted (mirror of `spec/fn_namespace_spec.rb`)
+
+## Verification
+
+- After each PR: `grep -rn "TbxIsoTml::<Class>" lib/` returns nothing
+- TBX fixture round-trips still pass
+- `bundle exec rake` green
+
+## Open question
+
+The shared-namespace role of TbxIsoTml (for elements used in both IsoSts
+and NisoSts hosts without their own version of the element) needs explicit
+documentation. Today the boundary is implicit. Consider an ADR documenting
+which elements are TBX-ISO-TML (shared) vs which are host-specific.