sts 0.6.5 → 0.6.7

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.

data/TODO.roadmap/08-register-versioning.md

@@ -0,0 +1,95 @@
+# C.08: Register versioning for STS schema versions
+
+**Status**: planning. Significant API design.
+**Original doc**: `TODO.sts-refactor/04-register-versioning.md` (HIGH
+priority, untouched).
+**Estimated effort**: large (multi-week).
+
+## Problem
+
+sts-ruby today ships a single `Sts::IsoSts` and `Sts::NisoSts` namespace.
+Each maps to one schema version (ISOSTS v1.1, NISO STS 1.0). Real-world
+documents use multiple versions:
+
+- ISOSTS v1.1 (2013, frozen)
+- NISO STS 1.0 (2017)
+- NISO STS 1.2 (2022, evolving)
+
+When a 1.2-specific element (`<processing-meta>`, `<code>`, `<legend>`) is
+modelled, it lives in `Sts::NisoSts::*` alongside 1.0 elements. There's no
+way to parse a document as "NISO STS 1.0 only" and reject 1.2 elements.
+
+## Goal
+
+Use lutaml-model's `Register` system to version the model classes. The
+mml gem already does this:
+
+```ruby
+module Mml
+  module V2
+    class Math < CommonElements
+      def self.lutaml_default_register
+        :mml_v2
+      end
+    end
+  end
+end
+```
+
+Each MathML version is a separate module with its own context. sts-ruby
+should follow the same pattern: `Sts::IsoSts::V1_1::*`, `Sts::NisoSts::V1_0::*`,
+`Sts::NisoSts::V1_2::*`.
+
+## Plan (high level)
+
+1. **API design** — decide caller-facing entrypoint:
+   - Option A: `Sts.parse(xml, version: :nisosts_1_0)` — explicit
+   - Option B: auto-detect from DOCTYPE / `dtd-version` attribute
+   - Option C: keep `Sts::NisoSts::*` as the latest alias, add
+     `Sts::NisoSts::V1_0::*` etc. for version-specific access
+2. **Re-namespace** — move every existing `Sts::NisoSts::*` class to
+   `Sts::NisoSts::V1_2::*` (or wherever it belongs based on schema
+   history). Keep backward-compat aliases.
+3. **Cross-version testing** — same fixture parsed under different
+   versions should accept/reject the right elements.
+4. **Version-specific elements** — `<processing-meta>` (1.2-only) lives
+   only in V1_2; parsing it under V1_0 raises (or warns).
+
+## Risks
+
+- **Breaking API change** — current callers use `Sts::NisoSts::Standard`
+  without a version. Any re-namespace breaks them.
+- **Cross-version references** — if V1_2::Standard contains V1_0::Paragraph
+  (because Paragraph hasn't changed), the type references cross versions.
+  Needs careful design.
+- **Migration burden** — large existing model surface.
+
+## Decision needed
+
+This is the largest remaining architectural work. Before starting:
+
+1. Confirm the use case (do downstream consumers actually need version
+   discrimination?)
+2. Decide the API (Options A/B/C above)
+3. Plan migration path for existing callers
+
+## Files affected
+
+- Every `lib/sts/niso_sts/*.rb` (~200 classes)
+- Every `lib/sts/iso_sts/*.rb` (~150 classes)
+- All specs that reference classes by current names
+
+## How to apply
+
+- Don't start until the design is approved
+- Read mml gem's `lib/mml/versioned_parser.rb` and
+  `lib/mml/context_configuration.rb` for the established pattern
+- Consider a small proof-of-concept (version one element family — e.g.,
+  `<list>` — across versions) before committing
+
+## Verification
+
+- Each version's classes round-trip its corresponding schema's fixtures
+- Cross-version parsing is explicitly tested
+- Existing callers can opt in incrementally (backward compat for at least
+  one release)

data/TODO.roadmap/09-test-coverage-gaps.md

@@ -0,0 +1,78 @@
+# D.09: Test coverage gaps
+
+**Status**: ongoing. Original doc: `TODO.sts-refactor/10-test-coverage.md`.
+**Estimated effort**: medium, distributed across future PRs.
+
+## Current state
+
+- **2563 examples, 0 failures**
+- Anti-pattern enforcement: 9 per-file checks in `spec/anti_patterns_spec.rb`
+- Per-model attribute-set assertions: ~50 models covered (mostly IsoSts
+  recent additions)
+- Round-trip coverage: `spec/round_trip/reference_docs_spec.rb` exercises
+  real fixtures
+- Coverage: 99.8% line coverage (per TODO.sts-refactor/10)
+
+## Gaps
+
+### 1. Schema-validation tests
+
+Currently absent. Each model is asserted against an attribute set in
+specs, but no test validates model output against the actual XSDs in
+`reference-docs/`. A schema-validation spec would catch:
+
+- Attributes the model invents (not in XSD)
+- Required attributes the model drops
+- Element nesting the XSD forbids
+
+Implementation: `Nokogiri::XML::Schema` to validate serialized output
+against `reference-docs/isosts-v1/xsd/ISOSTS.xsd` and
+`reference-docs/NISO-STS-extended-1-MathML3-XSD/`.
+
+### 2. Performance tests
+
+Currently absent. The user's TODO.sts-refactor/10 lists these as
+"needed". sts-ruby parses real ISO documents (some 1MB+); parsing time
+and memory pressure should be tracked.
+
+Implementation: `rspec-benchmark` or similar. Bench against the largest
+fixture (`spec/fixtures/mn-samples-iso-private/`). Track regressions
+across releases.
+
+### 3. Concurrent-parse tests
+
+`Lutaml::Model::TransformationRegistry` uses mutexes for thread safety
+(lib/lutaml/model/transformation_registry.rb:92-101). No spec covers
+concurrent parsing. Worth a thread-spawning test that hammers the
+registry from multiple threads to catch any race.
+
+### 4. Versioning tests (blocked on C.08)
+
+Once Register versioning exists, add specs that the same document parses
+differently under different versions, and that version-incompatible
+elements are rejected.
+
+### 5. Cross-namespace round-trip
+
+`spec/iso_sts/iso_sts_element_spec.rb` and `spec/sts_spec.rb` cover
+IsoSts and NisoSts separately. No spec exercises a TBX-in-ISOSTS document
+end-to-end (TBX elements inside IsoSts Standard with MathML 2 content).
+A round-trip test for `spec/fixtures/tbx-nisosts-0.2.xml`-style documents
+across all three namespaces would catch integration regressions.
+
+### 6. Profile validation (existing)
+
+`spec/profiles/iso_iec_validator_spec.rb` — 11 specs. Covers structural,
+metadata, originator, doc-type validation. Looks healthy.
+
+## How to apply
+
+- Add schema-validation spec first (highest value, mechanical to write)
+- Add performance spec next (gives a baseline before C.05/C.08 land)
+- Concurrent-parse spec is small and high-value — fit it in alongside any
+  future lutaml-model bump
+- Versioning and cross-namespace specs block on C.08
+
+## Verification
+
+Each new spec file passes locally and on CI. Coverage stays at ≥99.5%.

data/TODO.roadmap/10-iso-sts-common-attributes-module.md

@@ -0,0 +1,115 @@
+# D.10: IsoSts common-attribute module (DRY within namespace)
+
+**Status**: proposal. Needs approval before implementing.
+**Estimated effort**: medium (touches ~50 classes).
+
+## Problem
+
+Many IsoSts classes share the same attribute set:
+
+| Pattern | Attributes | Used by |
+|---|---|---|
+| Date parts | `id content_type specific_use xml_lang` | Day, Month, Season, Etal (partial) |
+| Contact (simple) | `id content_type specific_use content` | Phone, Fax |
+| xlink extension | `xlink_type xlink_href xlink_role xlink_title xlink_show xlink_actuate` | Abbrev, Email, ExtLink, Institution, InlineGraphic, MixedCitation |
+| Citation-common | `id content_type specific_use xml_lang originator` | (various) |
+
+This is fine-grained duplication. Each class is ~20-30 lines, mostly
+attribute declarations. A single attribute rename across the schema (e.g.,
+`xml:lang` semantics change) requires updating 30+ files.
+
+## Proposal
+
+Within the IsoSts namespace only (NOT cross-namespace — that's forbidden
+by the ADR), define modules:
+
+```ruby
+module Sts
+  module IsoSts
+    module CommonAttributes
+      # XLink attributes — included into classes that wrap XLink-extending elements
+      module Xlink
+        def self.included(base)
+          base.class_eval do
+            attribute :xlink_type, :string
+            attribute :xlink_href, :string
+            attribute :xlink_role, :string
+            attribute :xlink_title, :string
+            attribute :xlink_show, :string
+            attribute :xlink_actuate, :string
+          end
+        end
+      end
+
+      # Common attrs for simple text-with-id elements
+      module TextWithId
+        def self.included(base)
+          base.class_eval do
+            attribute :id, :string
+            attribute :content_type, :string
+            attribute :specific_use, :string
+            attribute :xml_lang, :string
+            attribute :content, :string, collection: true
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+Then:
+
+```ruby
+class Abbrev < Lutaml::Model::Serializable
+  include IsoSts::CommonAttributes::Xlink
+  # ... class-specific attrs
+end
+```
+
+## Trade-off
+
+**Pros**:
+- DRY at the attribute-declaration level
+- Single source of truth for common attribute sets
+- Easier to evolve (rename `xml_lang` → `xml_lang_attr` once)
+- Same pattern as `Mml::Base::CommonAttributes` in the mml gem
+
+**Cons**:
+- Adds indirection — readers must look at the module to know which attrs a
+  class has
+- Mapping (`map_attribute "xml:lang", to: :xml_lang`) still needs to be
+  declared per class
+- Risk of "module soup" if too many tiny modules are introduced
+
+## Decision needed
+
+This is a judgment call. The duplication today is annoying but not
+critical. The mml gem's precedent suggests the pattern is viable.
+
+Recommendation: **defer** until the namespace-coupling work (B.03, B.04)
+is complete. Doing it now would create churn on classes that are about to
+change anyway.
+
+## How to apply (if approved)
+
+1. Start with one module (XLink) — covers 5+ classes, lowest risk
+2. Convert one class, run tests, repeat
+3. Each conversion is its own commit (small, reviewable)
+4. Stop if the indirection starts hurting readability
+
+## Verification
+
+- All existing specs still pass
+- No spec needs to change (attribute-set assertions should be unchanged —
+  the module just provides the attribute declarations, the class still
+  exposes the same keys)
+- Rubocop clean
+
+## Anti-pattern note
+
+This proposal does NOT introduce cross-namespace sharing. The modules
+live in `Sts::IsoSts::CommonAttributes::*` and are only included into
+`Sts::IsoSts::*` classes. NisoSts would have its own
+`Sts::NisoSts::CommonAttributes::*` if it wants the same pattern. This
+respects the ADR 2026-05-07.

data/TODO.roadmap/11-docs-and-readme-refresh.md

@@ -0,0 +1,52 @@
+# D.11: Docs and README refresh
+
+**Status**: deferred. Low priority but accumulates debt.
+**Estimated effort**: small.
+
+## Problem
+
+Several docs reference outdated state:
+
+- `README.adoc` — likely doesn't mention 0.6.x features (V2/V3 MathML host
+  binding, the namespace-independence principle, the strengthened
+  anti-pattern enforcement)
+- `CLAUDE.md` — gives architecture guidance but predates the 2026-05-07
+  ADR, the recent unification work, the TODO.finalize/ series, and the
+  new TODO.roadmap/
+- `TODO.sts-refactor/` — mostly historical; the overview at
+  `00-overview.md` should link to `TODO.roadmap/00-overview.md` as the
+  current source of truth
+- Cross-references between TODO docs use stale ref counts (e.g.,
+  "63→16" appears in some places even after PRs reduced it to 11)
+
+## Plan
+
+1. **README** — refresh to mention:
+   - The IsoSts/NisoSts independence contract
+   - How to construct documents (which Fn/DispQuote/BoxedText class to use)
+   - MathML host binding (V2 for IsoSts, V3 for NisoSts)
+   - Anti-pattern enforcement (link to `spec/anti_patterns_spec.rb`)
+2. **CLAUDE.md** — refresh architecture section to reflect:
+   - The ADR 2026-05-07 (IsoSts/NisoSts independence)
+   - Current autoload conventions (no `require_relative`, no internal
+     `require`)
+   - The anti-pattern rules now enforced by spec
+3. **TODO.sts-refactor/00-overview.md** — add a header noting that
+  `TODO.roadmap/` is the current source of truth; this directory is
+  retained for history
+4. **Cross-reference cleanup** — search and update stale ref counts
+   across all TODO docs
+
+## How to apply
+
+- One PR with all doc updates
+- Coordinate with any in-flight code PRs to avoid stale doc references
+- Consider an ADR directory (`docs/adr/`) for the architectural decisions;
+  currently they're embedded in TODO docs which is fragile
+
+## Verification
+
+- All Markdown links resolve
+- Code examples in docs still work (copy-paste runnable)
+- No stale references to deleted classes (TbxIsoTml::Fn, TbxIsoTml::Math,
+  Sts::Mathml::Math, etc.)

data/TODO.sts-refactor/00-overview.md

@@ -19,7 +19,7 @@
 |---|------|----------|----------|--------------|
 | 01 | `01-mathml-delegation.md` | Anti-Pattern Fix | DONE | — |
 | 02 | `02-type-resolution.md` | Anti-Pattern Fix | DONE | — |
-| 03 | `03-namespace-coupling.md` | Architecture | IN PROGRESS (63→13 refs) | 01, 02 |
+| 03 | `03-namespace-coupling.md` | Architecture | IN PROGRESS (63→6 refs) | 01, 02 |
 | 04 | `04-register-versioning.md` | Architecture | HIGH | 01, 02 |
 | 05 | `05-missing-elements.md` | Feature Gap | MOSTLY DONE | 04 |
 | 06 | `06-missing-attributes.md` | Feature Gap | DONE | 04 |
@@ -166,7 +166,7 @@ grep -r "method_missing|respond_to_missing|Object.const_get|\.send" lib/
 - ~~Expand StringName usage (in contrib, element-citation, related-article — NISO STS 1.2)~~ → DONE: added to name-alternatives; already in person-group and mixed-citation
 
 ### Architectural Items (High Effort)
-- `03-namespace-coupling.md` — IN PROGRESS: 63→13 IsoSts→NisoSts references
+- `03-namespace-coupling.md` — IN PROGRESS: 63→6 IsoSts→NisoSts references
   remaining (issue #40). ISOSTS.xsd governs content models and all non-`@id`
   attributes; the `@id` follows the 86948b9 convention.
 - `04-register-versioning.md` — Version the models via lutaml-model Registers
@@ -193,7 +193,7 @@ the **NISO** XSD and applied the result to IsoSts.
 
 ## Next Action
 Two independent tracks:
-1. Finish `03` — the 13 remaining refs split across five recursive roots
+1. Finish `03` — the 6 remaining refs split across five recursive roots
    (`ElementCitation`, `PersonGroup`, `Collab`, `Source`, `TermDisplay`) and
    five child-bearing roots. `DispQuote` and `BoxedText` themselves are now
    IsoSts classes. The first 15 high-reuse dependency leaves are modelled,

data/TODO.sts-refactor/03-namespace-coupling.md

@@ -3,7 +3,7 @@
 **Priority**: HIGH
 **Category**: Architecture
 **Estimated Effort**: High
-**Status**: Partially done — 63 → 13 references (GitHub issue #40)
+**Status**: Partially done — 63 → 6 references (GitHub issue #40)
 
 ## Problem
 
@@ -14,6 +14,11 @@ evolves, so coupling them violates OCP.
 PR #31 reduced this from 157 to 63 references. Issue #40 reduced it further,
 from 63 to 16. The `IsoSts::DispQuote` / `IsoSts::BoxedText` addition then
 reduced it from 16 to 13 (Body#disp_quote, Sec#disp_quote, Sec#boxed_text).
+The `IsoSts::Attrib` addition then reduced it from 13 to 11
+(Array#attrib, TableWrapFoot#attrib) and filled the omission in DispQuote /
+BoxedText from PR #48. The License/TermHead/CustomMetaGroup closure then
+reduced it from 11 to 6 (Permissions#license, DefList#term_head, and
+IsoMeta/RegMeta/NatMeta#custom_meta_group).
 
 ## Content models from ISOSTS.xsd; `@id` from the 86948b9 convention
 
@@ -74,12 +79,24 @@ Non-`@id` attribute lists must be **generated** from the XSD, never hand-read:
   from NisoSts, which disagrees: `NisoSts::DispQuote` lacks `xml_lang` and
   `title`; `NisoSts::BoxedText` carries `form_type`/`is_form` that ISOSTS does
   not define). Children limited to existing IsoSts types; omitted children
-  (`attrib`, `speech`, `statement`, `verse-group`, `address`, `alternatives`,
+  (`speech`, `statement`, `verse-group`, `address`, `alternatives`,
   `array`, `chem-struct-wrap`, `fig-group`, `media`, `supplementary-material`,
   `table-wrap`, `table-wrap-group`, `disp-formula-group`, `mml:math`,
   `related-article`, `related-object`, `glossary`) are tracked below.
   `BoxedText#sts_object_id` (not `:object_id`) follows the `NisoSts::Graphic`
   convention to avoid clashing with `Object#object_id`. 3 refs.
+- **`Attrib` added** — mixed-content class modelled from ISOSTS.xsd with the
+  25 inline-element children that have IsoSts types today. Fills the
+  `attrib` gap left in `DispQuote` and `BoxedText` from the prior bullet.
+  2 refs (`Array#attrib`, `TableWrapFoot#attrib`). Omitted inline children
+  (`inline-supplementary-material`, `related-article`, `related-object`,
+  `element-citation`, `overline`, `roman`, `sans-serif`, `alternatives`,
+  `private-char`, `chem-struct`, `mml:math`, `target`, `tbx:entailedTerm`)
+  tracked below.
+- **License / TermHead / CustomMetaGroup closure added** — `License`,
+  `LicenseP`, `TermHead`, `CustomMetaGroup`, `CustomMeta`, `MetaName`, and
+  `MetaValue` modelled from ISOSTS.xsd. 5 refs (`Permissions#license`,
+  `DefList#term_head`, `IsoMeta/RegMeta/NatMeta#custom_meta_group`).
 
 ### Why classes and not plain `:string`
 
@@ -90,13 +107,15 @@ round-trip. For a scalar, `render_empty: :empty` recovers it; for a collection
 to `[]`, destroying the information at parse time before any render option
 applies. Content-only classes round-trip every case.
 
-## Remaining — 13 refs
+## Remaining — 6 refs
 
 **5 refs to 5 recursive roots**: `ElementCitation`, `PersonGroup`, `Collab`,
 `Source`, `TermDisplay`. Each reaches the same 78–79-element
 mutually-recursive core before existing IsoSts boundaries (`sec` → `p` →
-`disp-quote` → `p`). `DispQuote` and `BoxedText` themselves are now IsoSts
-classes and no longer in this list.
+`disp-quote` → `p`). `DispQuote`, `BoxedText`, `Attrib`, `License`,
+`TermHead`, and `CustomMetaGroup` are now IsoSts classes and no longer in
+this list. The remaining 6 are the recursive roots — see
+`TODO.roadmap/04-issue-40-recursive-roots.md` for the strategy.
 
 **8 refs to 5 child-bearing roots**, now measured after the first dependency
 layer: `attrib` (:1082) reaches 78 not-yet-modelled ISOSTS elements before

data/TODO.sts-refactor/09-autoload-cleanup.md

@@ -1,88 +1,53 @@
 # 09: Autoload and Require Cleanup
 
+**Status**: Refreshed 2026-07-26. Most items done; remaining items noted below.
 **Priority**: LOW
 **Category**: Cleanup
-**Estimated Effort**: Medium
-**Files Affected**: `lib/sts.rb`, `lib/sts/niso_sts.rb`, `lib/sts/iso_sts.rb`
-
-## Current Issues
-
-### 1. Autoload Alphabetization
-
-The autoload entries in `lib/sts/niso_sts.rb` should be alphabetically ordered. Check for any out-of-order entries when adding new elements.
-
-### 2. Moxml Monkey-Patch
-
-`lib/sts.rb` contains a monkey-patch on Moxml:
-
-```ruby
-Moxml::Adapter::Nokogiri.singleton_class.alias_method(:_orig_children, :children)
-Moxml::Adapter::Nokogiri.define_singleton_method(:children, &:children)
-```
-
-This patches an external library's behavior. If Moxml fixes the underlying issue, this will mask it or cause conflicts.
-
-**Action**: Add a comment explaining WHY this patch exists (the Nokogiri adapter bug it works around) and a link to the upstream issue if tracked.
-
-### 3. Orphaned/Unused Files
-
-After refactoring (TODOs 01-04), check for:
-- Files in `lib/sts/niso_sts/` that are no longer referenced
-- Files in `lib/sts/iso_sts/` that are no longer referenced
-- Unused requires
-
-### 4. Require Order Dependencies
-
-Some files may have implicit load-order dependencies (class A references class B, but B hasn't been loaded yet). The autoload system should handle this, but verify.
-
-### 5. Missing Requires for Cross-Namespace Types
-
-After fixing namespace coupling (TODO 03), ensure all cross-namespace references are replaced with proper requires or base type references.
-
-## File Structure After Cleanup
-
+**Files Affected**: `lib/sts.rb`, `lib/sts/iso_sts.rb`, `lib/sts/niso_sts.rb`
+
+## Done
+
+- **Moxml monkey-patch removed entirely** — upstream fix in moxml aa58888.
+  No code lives in `lib/sts.rb` patching `Moxml::Adapter::Nokogiri`.
+- **`lib/sts/mathml.rb` deleted** (commit 9e977a5) — Presentation MathML
+  unified on the mml gem (`Mml::V3::Math` for NisoSts, `Mml::V2::Math` for
+  IsoSts/TbxIsoTml per the host-binding fix in PR #45).
+- **`lib/sts/iso_sts/mathml2/` deleted** (this change) — dead-code hack file
+  that violated multiple anti-pattern rules. `IsoSts::Mathml2::Math` is gone.
+- **`lib/sts/content_groups/` deleted** — was dead code (the only caller,
+  `IsoSts::ContentGroups::HighlightElements`, was itself dead).
+- **`lib/sts/tbx_iso_tml/fn.rb` and `fn_group.rb` deleted** (PR #47) —
+  duplicates of `NisoSts::Fn` / `NisoSts::FnGroup` with conflicting Ruby
+  attribute names.
+- **Autoload registry is 1:1 with the directory tree** for both `iso_sts/`
+  and `niso_sts/`.
+- **`require_relative` is forbidden in `lib/`** — enforced by the
+  strengthened `spec/anti_patterns_spec.rb` (this change).
+
+## Current autoload conventions
+
+- Top-level: `lib/sts.rb` declares `autoload` for each top-level namespace
+  (`IsoSts`, `NisoSts`, `TbxIsoTml`, `Namespaces`, `Profiles`, `VERSION`).
+- Each namespace's `lib/sts/<namespace>.rb` file declares `autoload` for
+  every class in that namespace, organised by category with leading
+  comments. Alphabetical order within each category block.
+- External gems are eagerly required at the top of `lib/sts.rb`
+  (`require "lutaml/model"`, `require "mml"`). Internal code never uses
+  `require` or `require_relative`.
+
+## Remaining items
+
+- **`lib/sts/iso_sts.rb:3` has `require "mml"`** — redundant with the
+  top-level require in `lib/sts.rb:4`. Can be removed once verified no
+  load-order issue exists. Low priority.
+- **Verify no implicit load-order deps remain** — the autoload system
+  should resolve all references lazily. If a circular dependency emerges,
+  it usually indicates a misnamed constant or a missing autoload entry.
+
+## Verification
+
+```bash
+bundle exec rspec spec/anti_patterns_spec.rb    # catches require_relative,
+                                                 # internal require, etc.
+bundle exec rake                                 # full suite
 ```
-lib/
-├── sts.rb                           # Top-level: requires, Moxml patch (documented)
-├── sts/
-│   ├── namespaces.rb                # Namespace constants
-│   ├── mathml.rb                    # MathML wrapper (after TODO 01 fix)
-│   ├── mathml/                      # MathML-specific types (if needed)
-│   ├── base/                        # Shared base types (after TODO 03)
-│   │   ├── text/                    # Bold, Italic, Sub, Sup
-│   │   ├── struct/                  # Section, Paragraph, List
-│   │   ├── meta/                    # Title, Label, Caption
-│   │   └── refs/                    # Xref, BiblioRef
-│   ├── iso_sts/                     # ISOSTS namespace
-│   │   ├── iso_sts.rb               # Autoload declarations
-│   │   ├── v1_1/                    # ISOSTS v1.1 classes
-│   │   └── content_groups/          # Content group helpers
-│   ├── niso_sts/                    # NISO STS namespace
-│   │   ├── niso_sts.rb              # Autoload declarations
-│   │   ├── v1_0/                    # NISO STS 1.0 classes
-│   │   ├── v1_2/                    # NISO STS 1.2 classes
-│   │   ├── content_groups/          # Content group helpers
-│   │   ├── mml_content/             # MathML content elements
-│   │   └── xi.rb, ali.rb            # Namespace modules
-│   ├── tbx_iso_tml/                 # TBX namespace
-│   │   ├── tbx_iso_tml.rb           # Autoload declarations
-│   │   └── ...
-│   ├── content_groups/              # Shared content group helpers
-│   │   └── helpers.rb               # After TODO 02 fix
-│   └── profiles/                    # ISO/IEC validation layer (after TODO 08)
-```
-
-## Dependencies
-
-- `01-mathml-delegation.md` — MathML wrapper location
-- `03-namespace-coupling.md` — base types directory structure
-- `04-register-versioning.md` — versioned subdirectories
-
-## TODO Checklist
-
-- [x] Document Moxml monkey-patch with rationale (removed entirely — upstream fix in moxml aa58888)
-- [x] Audit autoload entries for alphabetical order
-- [x] After refactoring: remove orphaned files (deleted content_groups dead code)
-- [ ] After refactoring: verify no implicit load-order deps
-- [x] After refactoring: clean up unused requires
-- [x] Verify `bundle exec rake` passes cleanly