sts 0.6.6 → 0.6.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 201840881c86c036233c5bb1305bf176bbe6bf4ca0f43a22e370105cac0ed54f
-  data.tar.gz: 5845dd5fb849611a4a11bf173af68b3c226cf5c807d09bb721cf09cecdc8544b
+  metadata.gz: 53e7ba614487ea4d658f8292c403c6811255a85affd65ef9f98976ccc32aa426
+  data.tar.gz: a750e10d49eddc0664746e85114c7db000638b0a3e3addc4b352d179bb21684b
 SHA512:
-  metadata.gz: 20d4010381ed9daf225ecf13afc922b5cf338ec62318b24ee22554163885c815aa5db22257be600262fe8be9f7f8668a0569805e5a201db35b98a84e1fbfa982
-  data.tar.gz: c4078992f02ab4a9e6640e750d2f54b29136b187a58b9e42cc21e9a2cc76b7049c6e25f9b823e0827f2851468e3f0dcc618271526880ae3121be3f2fc5512d69
+  metadata.gz: a03cfc08c64cec197ee4a7a88a9ec41f46b3e94a80ea916092444be3419ec8c5aff06af3888094937be86cd7bbd2ed97b1663a688c16ba46650c0c61eed3cd60
+  data.tar.gz: 9ff6274690f18e27d2528497ffa5f4d0b5f3304e2636d276af5503b17318d6c86a090f3eeb583c0e889d26104878d8df9baed1b0d81ea227ed8b8be44e30573c

data/TODO.roadmap/00-overview.md

@@ -0,0 +1,80 @@
+# 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 fixes (file BUGREPORTs, propose patches) | 01, 02 |
+| B | Issue #40 namespace coupling completion | 03, 04 |
+| C | Architectural improvements (DRY, versioning, audit) | 05, 06, 07, 08 |
+| D | Quality, specs, and coverage | 09, 10, 11 |
+
+## Priority order
+
+The priority is "highest leverage per unit of risk" first:
+
+1. **B.03** (child-bearing roots): model `IsoSts::License`, `IsoSts::TermHead`,
+   `IsoSts::CustomMetaGroup` — closes 5 of 11 issue #40 refs in one PR. Low
+   risk, schema-correct, no recursion.
+2. **A.01, A.02** (lutaml-model BUGREPORTs): pure documentation, zero risk.
+   Unblocks C.06 (MathmlNamespace deduplication).
+3. **C.07** (TbxIsoTml misclassification audit): documents a deferred audit
+   (Xref, TableWrap, etc.) — pattern is already proven by Fn/FnGroup and
+   Math removals.
+4. **C.05** (Content MathML unification): 148 parallel classes in
+   `lib/sts/niso_sts/mml_content/` — same DRY argument as Presentation
+   MathML unification (commit 9e977a5).
+5. **B.04** (recursive roots): the heavy lift. Each root pulls a ~78-element
+   mutually-recursive core. Requires per-element planning. Most architecturally
+   significant.
+6. **C.08** (register versioning): lets ISOSTS v1.1, NISO STS 1.0, NISO STS 1.2
+   coexist without class-name clashes.
+7. **C.06** (MathmlNamespace deduplication): blocked on A.01.
+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-lutaml-model-namespace-scope-uri-matching.md

@@ -0,0 +1,111 @@
+# A.01: lutaml-model `namespace_scope` URI-based matching
+
+**Status**: BUGREPORT drafted; sts-ruby fix blocked on upstream.
+**Repo**: `lutaml/lutaml-model`
+**Estimated effort**: small (lutaml-model: ~20 lines + spec; sts-ruby: ~5 lines once landed)
+
+## Problem
+
+`namespace_scope` in `Lutaml::Model::Serializable.xml do … end` currently
+matches namespace classes by **identity** (`==`), not by URI. Two classes
+that declare the same URI/prefix are treated as different namespaces, so a
+parent that lists one cannot satisfy a child that declares the other.
+
+## Real-world symptom in sts-ruby
+
+`Sts::Namespaces::MathmlNamespace` (lib/sts/namespaces.rb) and
+`Mml::Namespace` (the mml gem's top-level namespace class) both encode:
+
+```ruby
+uri "http://www.w3.org/1998/Math/MathML"
+prefix_default "mml"
+```
+
+They are different classes (different `object_id`s). When `Mml::V3::Math` is
+nested inside `Sts::NisoSts::Standard`, the parent's `namespace_scope` lists
+`MathmlNamespace`. The child declares `Mml::Namespace`. Identity comparison
+fails, the `mml:` prefix is dropped on serialization.
+
+The current workaround — listing both classes in `namespace_scope`:
+
+```ruby
+namespace_scope [
+  ::Sts::Namespaces::MathmlNamespace,
+  ::Mml::Namespace,
+  ::Sts::Namespaces::TbxNamespace,
+  ::Lutaml::Xml::W3c::XlinkNamespace,
+]
+```
+
+— is a DRY violation. It documents the lutaml-model limitation rather than
+fixing it. See `lib/sts/iso_sts/standard.rb:18-19` and
+`lib/sts/niso_sts/standard.rb:20-21`.
+
+## Proposed lutaml-model fix
+
+In `Lutaml::Xml::NamespaceScope` (or wherever the membership check lives),
+compare by URI instead of (or in addition to) class identity. The public
+API doesn't change; only the matching semantics do.
+
+```ruby
+# pseudocode
+def includes?(namespace_class)
+  namespaces.any? do |declared|
+    declared.uri == namespace_class.uri
+  end
+end
+```
+
+## Files
+
+- `BUGREPORT.namespace-scope-uri-matching.md` in
+  `~/src/lutaml/lutaml-model/` (this track files it)
+- lutaml-model spec: `spec/lutaml/xml/namespace_scope_spec.rb` — assert that
+  two classes with the same URI are equivalent for `namespace_scope`
+- sts-ruby: remove the duplicated `MathmlNamespace` entry from
+  `IsoSts::Standard` and `NisoSts::Standard` once the upstream fix lands
+
+## Verification
+
+- Reproduction case (currently failing in 0.8.18):
+
+  ```ruby
+  class A < Lutaml::Model::Serializable
+    xml do
+      namespace SomeNs   # uri "urn:test", prefix "t"
+      element "a"
+    end
+  end
+  class B < Lutaml::Model::Serializable
+    xml do
+      namespace OtherNs  # also uri "urn:test", prefix "t" — different class
+      element "b"
+    end
+  end
+  class Parent < Lutaml::Model::Serializable
+    attribute :child, B
+    xml do
+      namespace_scope [SomeNs]
+      map_element "child", to: :child
+    end
+  end
+  # Currently: child's prefix is dropped on serialize.
+  # After fix: child's prefix is preserved (URIs match).
+  ```
+
+## Why not fix in sts-ruby today
+
+Cannot: the duplication is the only way to make `Mml::V3::Math` and
+`Mml::V2::Math` serialize with the `mml:` prefix inside STS Standard
+elements. Removing `MathmlNamespace` without the upstream fix would
+silently drop the prefix on every IsoSts/NisoSts document with MathML
+content.
+
+Track C.06 (MathmlNamespace deduplication) is the sts-ruby cleanup; it
+blocks on this track.
+
+## How to apply
+
+1. File BUGREPORT in `~/src/lutaml/lutaml-model/BUGREPORT.namespace-scope-uri-matching.md`.
+2. Optionally open PR upstream with the fix sketch above.
+3. After upstream lands and sts-ruby bumps its lutaml-model dep, do C.06.

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/06-mathml-namespace-deduplication.md

@@ -0,0 +1,59 @@
+# C.06: MathmlNamespace deduplication
+
+**Status**: blocked on A.01 (lutaml-model namespace_scope URI matching).
+**Estimated effort**: trivial (delete one class, two `namespace_scope`
+entries).
+
+## Problem
+
+`Sts::Namespaces::MathmlNamespace` (lib/sts/namespaces.rb:5-8) and
+`Mml::Namespace` (mml gem's top-level namespace class) both encode:
+
+```ruby
+uri "http://www.w3.org/1998/Math/MathML"
+prefix_default "mml"
+```
+
+Two classes, same URI/prefix. The current `namespace_scope` workaround on
+`IsoSts::Standard` and `NisoSts::Standard` lists both:
+
+```ruby
+namespace_scope [
+  ::Sts::Namespaces::MathmlNamespace,
+  ::Mml::Namespace,
+  ::Sts::Namespaces::TbxNamespace,
+  ::Lutaml::Xml::W3c::XlinkNamespace,
+]
+```
+
+This is the documented smell noted in memory `mml-gem-integration-failure`
+("namespace_scope duplication is a known smell"). It exists because
+lutaml-model's `namespace_scope` matches by class identity, not by URI.
+
+## Plan
+
+Once A.01 lands upstream and sts-ruby has bumped its lutaml-model dep:
+
+1. Delete `Sts::Namespaces::MathmlNamespace` from `lib/sts/namespaces.rb`.
+2. Replace both `namespace_scope` entries with `::Mml::Namespace` only.
+3. Audit any other references to `MathmlNamespace` (likely only
+   `lib/sts/niso_sts/mml_content.rb:10` — but that whole module is
+   being deleted by C.05).
+
+## Verification
+
+- `grep -rn "MathmlNamespace" lib/` returns nothing
+- TBX round-trip fixtures still preserve `<mml:math>` prefix
+- NISO STS fixtures still preserve `<mml:math>` prefix
+- IsoSts fixtures (V2) still preserve `<mml:math>` prefix
+
+## How to apply
+
+- Coordinate with A.01 — file the BUGREPORT first, then either propose the
+  upstream fix or wait for it
+- When the upstream fix is in a released lutaml-model version, bump
+  sts.gemspec and ship this cleanup as a follow-up PR
+
+See also: TODO.sts-refactor/03-namespace-coupling.md "MathML wrapper"
+discussion (now historical — the wrapper itself was deleted in 9e977a5,
+but the namespace duplication remains).