chemicalml 0.1.0

data/TODO.align/16-schema24-convention-coverage.md

@@ -0,0 +1,33 @@
+# 16 — Schema24 convention coverage
+
+**Status:** complete
+**Depends on:** 10
+
+## Goal
+
+All convention specs today build `Chemicalml::Cml::Document.new(...)`
+which is an alias for Schema3. The constraints are written to accept
+both schemas (after task 10, via role modules), but no spec verifies
+Schema24 documents.
+
+Add parallel examples in each convention spec that build Schema24
+documents and verify the same violations fire.
+
+## Why
+
+- Confidence that the role-module refactor (task 10) actually works.
+- Catches regressions where a future edit accidentally only checks
+  Schema3.
+
+## Deliverables
+
+- [ ] `spec/chemicalml/convention/convention_spec.rb` extended with
+      Schema24 equivalents of the molecular, compchem, and dictionary
+      constraint specs.
+- [ ] A shared example helper to avoid duplicating the schema24 path
+      for every constraint.
+
+## Acceptance
+
+- At least one Schema24-path example per convention.
+- All examples pass.

data/TODO.align/17-final-spec-lint.md

@@ -0,0 +1,28 @@
+# 17 — Final spec + lint pass
+
+**Status:** complete
+**Depends on:** all
+
+## Goal
+
+Run the full suite, audit forbidden patterns, document final state.
+
+## Deliverables
+
+- [ ] `bundle exec rspec spec/chemicalml/` green.
+- [ ] `grep -rn 'require_relative' lib/` clean.
+- [ ] `grep -rn '^require .chemicalml' lib/` clean.
+- [ ] `grep -rn 'respond_to?' lib/` clean.
+- [ ] `grep -rn 'instance_variable_set\|instance_variable_get' lib/`
+      clean.
+- [ ] `grep -rn '[^a-zA-Z_\.]send[ ]*(' lib/` clean.
+- [ ] `grep -rn 'is_a?(Chemicalml::Cml::Schema' lib/chemicalml/convention/`
+      clean.
+- [ ] Both `Schema3::Configuration` and `Schema24::Configuration` are
+      under 20 lines.
+- [ ] `TODO.align/README.round2.md` index shows every workstream
+      `complete`.
+
+## Acceptance
+
+All of the above verified.

data/TODO.align/README.md

@@ -0,0 +1,27 @@
+# TODO.align
+
+Master plan for aligning the `chemicalml` gem's architecture with the
+patterns established by the sibling `mml` gem
+(https://github.com/plurimath/mml). Each file in this directory is one
+workstream.
+
+These tasks refactor the existing scaffolding so that schema versions,
+namespaces, and round-trip validation follow the same idioms `mml` uses
+for MathML 2/3/4.
+
+| # | Workstream | Status | Depends on |
+|---|---|---|---|
+| 01 | [Cml::Base shared mixins](01-cml-base-mixins.md) | complete | — |
+| 02 | [Real Schema3/Schema24 hierarchies](02-real-schema-hierarchies.md) | complete | 01 |
+| 03 | [Configuration + lutaml_default_register](03-configuration.md) | complete | 02 |
+| 04 | [Top-level parse / serialize entry points](04-parse-entry-points.md) | complete | 02, 03 |
+| 05 | [Schema-aware Translator](05-schema-aware-translator.md) | complete | 02 |
+| 06 | [Replace respond_to? with is_a?](06-no-respond-to.md) | complete | 02 |
+| 07 | [Canon-based semantic XML comparison](07-canon-xml-comparison.md) | complete | — |
+| 08 | [Expand fixtures corpus](08-expand-fixtures.md) | complete | 02 |
+| 09 | [Final spec + lint pass](09-final-spec-lint.md) | complete | all |
+
+**All workstreams complete.** 136 examples, 0 failures. Zero
+`require_relative`, zero intra-library `require`, zero `respond_to?`,
+zero `instance_variable_set`/`instance_variable_get`, zero private
+`send` in `lib/`.

data/TODO.align/README.round2.md

@@ -0,0 +1,24 @@
+# TODO.align (round 2)
+
+Architectural improvements identified after the round-1 alignment with
+the `mml` patterns. Each file documents one focused workstream.
+
+Round 1 (TODO.align/01–09) established the versioned class hierarchies,
+configuration, and convention framework. Round 2 (TODO.align/10–17)
+eliminates remaining OCP / DRY / SSOT violations.
+
+| # | Workstream | Status | Depends on |
+|---|---|---|---|
+| 10 | [Role marker modules](10-role-marker-modules.md) | complete | — |
+| 11 | [DRY Configuration registration](11-dry-configuration.md) | complete | — |
+| 12 | [Wire class definition macro](12-wire-class-macro.md) | complete | 11 |
+| 13 | [Wire XML namespace setup](13-wire-namespace.md) | complete | — |
+| 14 | [Schema 2.4 correctness — drop `<module>`](14-schema24-correctness.md) | complete | 11 |
+| 15 | [Canon-based fixture round-trip](15-canon-fixture-roundtrip.md) | complete | 13 |
+| 16 | [Schema24 convention coverage](16-schema24-convention-coverage.md) | complete | 10 |
+| 17 | [Final spec + lint pass](17-final-spec-lint.md) | complete | all |
+
+**All workstreams complete.** 142 examples, 0 failures. Schema3 and
+Schema24 configurations are 17 and 19 lines respectively. 66
+boilerplate class files eliminated (33 per schema). Zero forbidden
+patterns in `lib/`.

data/TODO.cml-full/01-reference-docs.md

@@ -0,0 +1,43 @@
+# 01 — Reference docs
+
+**Status:** pending
+**Depends on:** —
+
+## Goal
+
+Pull every authoritative source document from xml-cml.org into
+`reference-docs/` so the gem ships with its own canonical references.
+These files are archival source — never delete or edit them.
+
+## Deliverables
+
+- [ ] `reference-docs/cmllite.html` — the CMLLite paper
+      (https://www.xml-cml.org/schema/cmllite.html)
+- [ ] `reference-docs/conventions/index.md` — the conventions landing page
+      (http://www.xml-cml.org/convention/)
+- [ ] `reference-docs/conventions/molecular.md`
+- [ ] `reference-docs/conventions/compchem.md`
+- [ ] `reference-docs/conventions/dictionary.md`
+- [ ] `reference-docs/conventions/unit-dictionary.md`
+- [ ] `reference-docs/conventions/unitType-dictionary.md`
+- [ ] `reference-docs/dictionaries/compchem.xml` — the live CompChem
+      dictionary at http://www.xml-cml.org/dictionary/compchem/
+- [ ] `reference-docs/dictionaries/unit.xml` — SI/non-SI unit dictionary
+- [ ] `reference-docs/dictionaries/unitType.xml` — unit-type dictionary
+- [ ] A note at the top of each file pointing to its source URL and the
+      CC-BY-3.0 license
+
+## Implementation notes
+
+Use `bundle exec rake reference:fetch` (added in
+`lib/tasks/reference_fetch.rake`) — this downloads everything in one
+shot, skips files that already exist, and prints a summary. Do **not**
+commit generated files without reviewing them; some upstream URLs may
+redirect or 404 — log those and move on, don't fail the whole task.
+
+## Acceptance
+
+- All listed files exist under `reference-docs/`.
+- Each file starts with a one-line `<!-- Source: URL, CC-BY-3.0 -->` comment
+  (or Markdown equivalent).
+- `bundle exec rake reference:fetch` is idempotent.

data/TODO.cml-full/02-schema-versioned-model.md

@@ -0,0 +1,70 @@
+# 02 — Schema-versioned wire model
+
+**Status:** pending
+**Depends on:** 01
+
+## Goal
+
+Support both CML schema 2.4 and schema 3 as first-class wire formats.
+The two XSDs (already in `reference-docs/schemas/`) are the source of
+truth for element/attribute names and content models.
+
+## Why split the namespace
+
+Schema 3 loosened the content model of schema 2.4 — many elements
+gained optional children, some attribute types changed, and a few new
+elements were added. Conflating the two into one class set:
+
+- forces every user to pay schema-3-only validation cost,
+- makes it impossible to express "this element only exists in schema 3",
+- hides which version a round-trip targets.
+
+Keeping them separate (Schema24 / Schema3 namespaces) gives users an
+explicit choice and keeps each class honest about its own version.
+
+## Deliverables
+
+- [ ] `Chemicalml::Schema` registry: maps version symbols (`:schema24`,
+      `:schema3`) to their XSD path, namespace, and the wire-class
+      namespace.
+- [ ] `Chemicalml::Cml::Schema3::*` — schema 3 wire classes
+- [ ] `Chemicalml::Cml::Schema24::*` — schema 2.4 wire classes
+- [ ] A shared mixin `Chemicalml::Cml::Common` for the elements that
+      have **identical** shapes in both versions (most of them —
+      schema 3 is largely a superset). The mixin carries `attribute`
+      declarations and the `xml do ... end` mapping block; the
+      schema-specific class includes it.
+- [ ] For elements that differ between versions (e.g. `molecule`'s
+      content model), each version gets its own dedicated class — no
+      shared mixin.
+- [ ] Update `Chemicalml::Cml::Translator` so it accepts a
+      `schema:` keyword and dispatches to the right wire class set.
+
+## Scope of classes to add
+
+Driven by what the conventions and example fixtures need:
+
+Common (likely shared via mixin): `atom`, `atomArray`, `bond`,
+`bondArray`, `name`, `identifier`, `formula`, `property`, `parameter`,
+`scalar`, `array`, `matrix`, `label`, `module`, `list`, `reaction`,
+`reactantList`, `reactant`, `productList`, `product`, `reactionList`,
+`substance`, `substanceList`, `spectator`, `spectatorList`,
+`parameterList`, `propertyList`, `metadata`, `metadataList`,
+`atomParity`, `bondStereo`, `atomSet`, `bondSet`, `torsion`, `angle`,
+`length`, `zMatrix`, `crystal`, `lattice`, `latticeVector`,
+`cellParameter`, `eigenvector`.
+
+Differences to honor:
+
+- Schema 2.4: stricter content models (e.g. `<molecule>` cannot have
+  arbitrary child modules).
+- Schema 3: introduced `<module>` as a generic grouping container;
+  loosened `<cml>` to allow any top-level CML element.
+
+## Acceptance
+
+- All schema-versioned wire classes are loadable.
+- Both schema XSDs round-trip the example fixtures in their respective
+  `spec/fixtures/schema{24,3}/` directories.
+- No `require_relative` anywhere — all loading via autoload in
+  `lib/chemicalml/cml/schema3.rb`, `schema24.rb`, etc.

data/TODO.cml-full/03-fixtures-scrape.md

@@ -0,0 +1,52 @@
+# 03 — Fixtures scrape
+
+**Status:** pending
+**Depends on:** 01
+
+## Goal
+
+Pull every example CML document from xml-cml.org/examples/ into
+`spec/fixtures/`, organized by schema version and category. These are
+the canonical test corpus for round-trip and convention-conformance
+specs.
+
+## Source URLs
+
+- http://www.xml-cml.org/examples/schema3/molecular/ — schema 3 molecular
+- http://www.xml-cml.org/examples/schema3/compchem/  — schema 3 compchem
+- http://www.xml-cml.org/examples/schema24/          — schema 2.4
+
+Each landing page is an HTML index linking to per-example `.html`
+viewer pages that themselves embed the raw CML. The scraper has to
+walk the index, fetch each example page, and extract the CML block.
+
+## Deliverables
+
+- [ ] `lib/tasks/scrape_fixtures.rake` exposing
+      `bundle exec rake fixtures:scrape`. Idempotent — skips files that
+      already exist.
+- [ ] `spec/fixtures/schema3/molecular/*.cml`
+- [ ] `spec/fixtures/schema3/compchem/*.cml`
+- [ ] `spec/fixtures/schema24/*.cml`
+- [ ] A smoke spec `spec/chemicalml/fixtures_round_trip_spec.rb` that
+      loads every `.cml` fixture, runs
+      `Chemicalml::Cml::Schema3::Document.from_xml(...)`, and asserts
+      `to_xml` produces a document the parser can re-read.
+
+## Implementation notes
+
+- Use `Net::HTTP` directly — no extra gem dependency. Honour a 1-second
+  delay between requests to be polite.
+- File names: derive from the example title, slugged to
+  `[a-z0-9_-]+`. Preserve uniqueness with a numeric suffix if needed.
+- The example index pages render titles like "minimal molecule 1" —
+  slug those to `minimal_molecule_1.cml`.
+- If a fetch fails (404, redirect to a different host), record the URL
+  in `spec/fixtures/.scrape-log` and continue — don't abort the run.
+
+## Acceptance
+
+- All three fixture directories exist with the expected example count
+  (molecular ~36, compchem ~5, schema24 varies).
+- The round-trip smoke spec is green.
+- Re-running `rake fixtures:scrape` makes no changes.

data/TODO.cml-full/04-convention-framework.md

@@ -0,0 +1,69 @@
+# 04 — Convention framework
+
+**Status:** pending
+**Depends on:** 02
+
+## Goal
+
+Model the five conventions CML publishes, plus a generic
+constraint-evaluation framework so adding a new rule is a registration,
+not an edit.
+
+## Conventions
+
+Each is identified by its namespace URI and the QName used in the
+`convention=` attribute:
+
+| Convention        | QName                     | Namespace URI                                     |
+|-------------------|---------------------------|---------------------------------------------------|
+| Molecular         | `convention:molecular`    | http://www.xml-cml.org/convention/molecular       |
+| CompChem          | `convention:compchem`     | http://www.xml-cml.org/convention/compchem        |
+| Dictionary        | `convention:dictionary`   | http://www.xml-cml.org/convention/dictionary      |
+| Unit dictionary   | `convention:unit-dictionary` | http://www.xml-cml.org/convention/unit-dictionary |
+| UnitType dictionary | `convention:unitType-dictionary` | http://www.xml-cml.org/convention/unitType-dictionary |
+
+## Deliverables
+
+- [ ] `Chemicalml::Convention::Base` — abstract base. Carries the
+      namespace URI, a human-readable name, and a registry of
+      constraint classes.
+- [ ] `Chemicalml::Convention::Registry` — maps QName → convention
+      instance. `Convention::Registry.lookup("convention:molecular")`
+      returns the convention.
+- [ ] `Chemicalml::Convention::Constraint` — abstract base for a single
+      rule. Each constraint implements `check(node, context)` returning
+      either `nil` (pass) or a `Violation` instance.
+- [ ] `Chemicalml::Convention::Violation` — value object with `path`,
+      `message`, `severity` (`:error` / `:warning`).
+- [ ] `Chemicalml::Convention::Molecular` — preloads every constraint
+      listed in the molecular convention spec (atom ids unique, bond
+      refs in scope, etc.).
+- [ ] `Chemicalml::Convention::Compchem` — constraints around the
+      `module` / `jobList` / `job` / `initialization` / `calculation`
+      / `finalization` / `environment` structure.
+- [ ] `Chemicalml::Convention::Dictionary`, `UnitDictionary`,
+      `UnitTypeDictionary` — dictionary-element constraints (entry id
+      uniqueness, required `term`, etc.).
+- [ ] `Chemicalml::Convention.validate(document, qname:)` — runs every
+      constraint for the named convention and returns the violation
+      list.
+
+## Design constraints (non-negotiable)
+
+- New constraint = **register a class**, never edit a switch statement.
+  The molecular convention's constraints live in
+  `lib/chemicalml/convention/molecular/constraints/`, one class per
+  file, registered in `lib/chemicalml/convention/molecular.rb`.
+- The framework never knows about specific constraints — it only
+  iterates whatever the convention registered.
+- Constraints may walk the tree using `Node#accept(visitor)` from the
+  canonical model — they don't have to re-implement traversal.
+
+## Acceptance
+
+- All five conventions are registered and return non-empty
+  constraint sets.
+- A molecular-convention-invalid document (e.g. duplicate atom ids)
+  produces at least one `Violation` with `severity: :error`.
+- Specs cover at least one positive and one negative case per
+  convention.

data/TODO.cml-full/05-dictionary-layer.md

@@ -0,0 +1,77 @@
+# 05 — Dictionary layer
+
+**Status:** pending
+**Depends on:** 04
+
+## Goal
+
+Model the CML dictionary convention and ship built-in dictionaries as
+YAML, with a typed entry schema. Dictionaries must be queryable by id
+and by QName prefix.
+
+## YAML entry schema
+
+Each entry is one YAML document under the dictionary's namespace:
+
+```yaml
+---
+namespace: http://www.xml-cml.org/dictionary/compchem/
+prefix: compchem
+title: Computational Chemistry Dictionary
+description: |
+  Terms used by the CompChem convention.
+entries:
+  - id: jobList
+    term: Job List
+    definition: |
+      A list of sequential computational jobs.
+    description: |
+      <p>A jobList...</p>     # xhtml content as a string
+    data_type: xsd:string     # optional; QName
+    unit_type: unitType:none  # required; QName
+    units: unit:none          # optional; QName
+    enum:
+      kind: open              # open | closed
+      values: []              # populated only when kind: closed
+    links:
+      - rel: seeAlso
+        href: http://example.org/foo
+    source_code: |
+      <code>...</code>        # optional xhtml/code block
+```
+
+The dictionary itself is the file; the schema is one entry per
+record under `entries:`.
+
+## Deliverables
+
+- [ ] `Chemicalml::Dictionary` — top-level model: `namespace`,
+      `prefix`, `title`, `description`, `entries` (collection).
+      Built on `Lutaml::Model::Serializable` with YAML mapping.
+- [ ] `Chemicalml::Dictionary::Entry` — typed model with all the
+      fields above. `enum` is itself a small model with `kind:` and
+      `values:`.
+- [ ] `Chemicalml::Dictionary::Link` — `rel`, `href`, optional `title`.
+- [ ] `Chemicalml::Dictionary::Registry` — loads every `.yaml` under
+      `data/dictionaries/`, indexes by both `prefix:` and `namespace:`.
+      `Registry.lookup("compchem:totalEnergy")` returns the entry.
+- [ ] Built-in YAML files under `data/dictionaries/`:
+      `compchem.yaml`, `unit.yaml`, `unit_type.yaml`, `cml.yaml`
+      (core CML terms referenced from the dictionaries page).
+- [ ] `Chemicalml::Dictionary.load(name)` — convenience loader.
+
+## Design constraints
+
+- Entries are loaded from YAML, never hand-coded in Ruby.
+- The model classes do NOT serialize back to YAML by hand — they
+  use lutaml-model's YAML adapter via `yaml do ... end` mapping blocks.
+- No `require_relative` in any of these files.
+
+## Acceptance
+
+- `Chemicalml::Dictionary.load("compchem")` returns a populated
+  `Dictionary` with at least the entries cited in the compchem
+  convention (`jobList`, `job`, `initialization`, `calculation`,
+  `finalization`, `environment`, `totalEnergy`, etc.).
+- The registry resolves QNames of the form `prefix:id` correctly.
+- Round-trip: load YAML → model → re-serialize to YAML → reload → equal.

data/TODO.cml-full/06-extend-canonical-translator.md

@@ -0,0 +1,60 @@
+# 06 — Extend canonical model + translator
+
+**Status:** pending
+**Depends on:** 02, 05
+
+## Goal
+
+The canonical `Chemicalml::Model` and the `Cml::Translator` currently
+cover the molecule / atom / bond / reaction subset. The full CML
+conventions need formula, property, parameter, scalar/array/matrix,
+module (the compchem container), label, and metadata. Bring both up to
+speed together so round-trip coverage matches the example fixtures.
+
+## Deliverables
+
+### Canonical model additions (`Chemicalml::Model::*`)
+
+- [ ] `Formula` — `concise`, `inline`, optional `atom_array`, `count`
+- [ ] `Property` — wraps a single value container, has `dict_ref`, `title`
+- [ ] `Parameter` — same shape as Property but used for inputs
+- [ ] `Scalar` — `value`, `data_type`, `units`
+- [ ] `Array` — `values` (split string), `data_type`, `units`, `size`
+- [ ] `Matrix` — `values`, `rows`, `columns`, `data_type`, `units`
+- [ ] `Label` — `value`, `dict_ref`
+- [ ] `Module` — generic grouping container, `dict_ref`, `role`, ordered children
+- [ ] `Metadata` — `name`, `content`, `convention`
+- [ ] `PropertyList`, `ParameterList`, `MetadataList` — collection wrappers
+
+### CML wire additions (`Chemicalml::Cml::*` or per-schema)
+
+- [ ] Same set as above, one lutaml-model class each, with the right
+      XML element name and attribute names from the XSDs.
+
+### Translator updates
+
+- [ ] Add a translation rule for every new model class. Each rule is a
+      pair of methods on `Translator` following the existing
+      `*_to_canonical` / `*_from_canonical` pattern.
+- [ ] Where the wire name differs from the Ruby name, the CML class's
+      `xml do ... end` block carries the rename (e.g.
+      `map_attribute "elementType", to: :element_type`). The translator
+      doesn't do key-swapping.
+- [ ] Add a `value_attributes` implementation for every new canonical
+      class so equality and visitor traversal work.
+
+## Design constraints
+
+- One concern per file (MECE). Adding `Scalar` =
+  `model/scalar.rb` + `cml/scalar.rb` (or per-schema) + translator
+  rule + spec. Don't bundle several elements into one file.
+- The translator is the only class that imports both namespaces.
+- No `def to_h` / `def from_h` / `def to_xml` / `def from_xml` on any
+  model or wire class.
+
+## Acceptance
+
+- Every example fixture round-trips through
+  `Document.from_xml(...).to_xml` and re-parses to an equal document.
+- New model classes have specs covering construction, equality, and
+  translator round-trip.

data/TODO.cml-full/07-attribution-notices.md

@@ -0,0 +1,42 @@
+# 07 — Attribution & notices
+
+**Status:** pending
+**Depends on:** —
+
+## Goal
+
+The CML conventions, schema, examples, and dictionaries are published
+by xml-cml.org under a Creative Commons Attribution 3.0 (CC-BY-3.0)
+license. The gem redistributes derived works (model classes,
+dictionaries as YAML, scraped fixtures, archived convention specs).
+Proper attribution is both legally required and a basic courtesy to
+the people who built CML.
+
+## Deliverables
+
+- [ ] `NOTICES.adoc` at the repo root crediting:
+      - Peter Murray-Rust, Joe Townsend, Sam Adams, and the wider
+        CML community at the University of Cambridge.
+      - Weerapong Phadungsukanan, Jens Thomas, Nick England,
+        Daniel Lowe, Hannah Barjat, Alex Wade.
+      - The xml-cml.org project and the Chemical Markup Language
+        community.
+  Each credit lists what they contributed (convention editors,
+  dictionary authors, schema maintainers, etc.).
+- [ ] A "Third-party content" section in `NOTICES.adoc` listing every
+      file under `reference-docs/` and `spec/fixtures/` that derives
+      from xml-cml.org, with the upstream URL and the CC-BY-3.0
+      license notice.
+- [ ] A short "Acknowledgements" section in `README.adoc` mirroring
+      the above.
+- [ ] Each archived reference doc keeps its own one-line source-and-
+      license attribution at the top (added when fetched, see
+      `01-reference-docs.md`).
+
+## Acceptance
+
+- `NOTICES.adoc` exists, names every contributor surfaced in the
+  convention pages, and reproduces the CC-BY-3.0 notice.
+- README.adoc has a visible acknowledgements section.
+- `git ls-files reference-docs spec/fixtures | wc -l` non-zero (i.e.,
+  we actually redistribute some upstream content).

data/TODO.cml-full/08-autoload-only.md

@@ -0,0 +1,48 @@
+# 08 — Autoload-only loading
+
+**Status:** pending
+**Depends on:** —
+
+## Goal
+
+The user's global rule (and CLAUDE.md) forbid `require_relative` and
+intra-library `require` inside `lib/`. The current codebase still uses
+them. Migrate every occurrence to Ruby `autoload` declared in the
+immediate parent namespace's file.
+
+## Files to fix
+
+The following files use `require_relative` or intra-library `require`
+for code that lives inside this gem:
+
+- `lib/chemicalml/model/document.rb`
+- `lib/chemicalml/model/reaction.rb`
+- `lib/chemicalml/model/reaction_list.rb`
+- `lib/chemicalml/model/reactant.rb`
+- `lib/chemicalml/model/reactant_list.rb`
+- `lib/chemicalml/model/product.rb`
+- `lib/chemicalml/model/product_list.rb`
+- `lib/chemicalml/cml/translator.rb` (imports both Model and Cml — this
+  one is legitimate because Translator is the *adapter* between the two
+  namespaces; verify it still works via autoload, then drop the explicit
+  requires).
+- `chemicalml.gemspec` (`require_relative "lib/chemicalml/version"`) —
+  this is the *only* legitimate use; gemspecs run before the gem is
+  loaded, so they cannot use autoload. Leave this one alone.
+
+## Deliverables
+
+- [ ] Audit `lib/` for every `require_relative` and every `require`
+      whose target is a file inside `lib/chemicalml/`.
+- [ ] Replace each with an `autoload` declaration in the immediate
+      parent namespace's file. If the parent namespace file doesn't
+      exist, create it.
+- [ ] Confirm the spec suite still passes (`bundle exec rspec`).
+- [ ] Add a RuboCop `Style/RequireRelative`-style guard to
+      `.rubocop.yml` (or a custom cop) so this can't regress.
+
+## Acceptance
+
+- `grep -rn 'require_relative' lib/` returns only the gemspec line.
+- `grep -rn "^require ['\"]chemicalml/" lib/` returns nothing.
+- Full spec suite green.

data/TODO.cml-full/09-spec-coverage.md

@@ -0,0 +1,38 @@
+# 09 — Spec coverage
+
+**Status:** pending
+**Depends on:** 02, 04, 05, 06
+
+## Goal
+
+Every public method has specs. Every fixture round-trips. Every
+convention has at least one passing and one failing case. No `double`.
+
+## Deliverables
+
+- [ ] `spec/chemicalml/cml/schema3/*_spec.rb` — one per wire class
+- [ ] `spec/chemicalml/cml/schema24/*_spec.rb` — one per wire class
+- [ ] `spec/chemicalml/model/*_spec.rb` — one per canonical class
+- [ ] `spec/chemicalml/cml/translator_spec.rb` — extended to cover the
+      new model classes added in `06-extend-canonical-translator.md`
+- [ ] `spec/chemicalml/convention/*_spec.rb` — one per convention,
+      positive and negative paths
+- [ ] `spec/chemicalml/dictionary_spec.rb` — registry lookup,
+      round-trip YAML → model → YAML
+- [ ] `spec/chemicalml/fixtures_round_trip_spec.rb` — iterates every
+      `.cml` file under `spec/fixtures/`, parses, re-serializes,
+      re-parses, asserts equality
+
+## Constraints
+
+- Never `double`. Use real instances or `Struct.new`.
+- Specs assert on **state**, not on "should have received" method-call
+  counts.
+- Specs live under `spec/chemicalml/`, mirroring `lib/chemicalml/`.
+
+## Acceptance
+
+- `bundle exec rspec` is green.
+- `bundle exec rspec --profile 10` shows no examples taking a
+  surprising amount of time (sanity check — no accidental network or
+  file I/O in hot paths).

data/TODO.cml-full/README.md

@@ -0,0 +1,23 @@
+# TODO.cml-full
+
+Master plan for the full CML implementation of the `chemicalml` gem.
+
+Each file in this directory is one workstream. Numbering is the
+suggested implementation order; later tasks depend on earlier ones
+where noted.
+
+| # | Workstream | Status | Depends on |
+|---|---|---|---|
+| 01 | [Reference docs](01-reference-docs.md) — fetch & archive cmllite, conventions, dictionaries | pending | — |
+| 02 | [Schema-versioned wire model](02-schema-versioned-model.md) — split Cml into Schema3 / Schema24 | pending | 01 |
+| 03 | [Fixtures scrape](03-fixtures-scrape.md) — pull all example CML into `spec/fixtures/` | pending | 01 |
+| 04 | [Convention framework](04-convention-framework.md) — registry + 5 conventions | pending | 02 |
+| 05 | [Dictionary layer](05-dictionary-layer.md) — model + YAML store + entries | pending | 04 |
+| 06 | [Extend canonical model + translator](06-extend-canonical-translator.md) — formula/property/parameter/scalar/array/matrix/module/label | pending | 02, 05 |
+| 07 | [Attribution & notices](07-attribution-notices.md) — credit xml-cml.org, CC-BY-3.0 | pending | — |
+| 08 | [Autoload-only loading](08-autoload-only.md) — remove all `require_relative` from lib/ | pending | — |
+| 09 | [Spec coverage](09-spec-coverage.md) — every public method, every fixture round-trip | pending | 02, 04, 05, 06 |
+
+When picking up work, claim the lowest-numbered pending task and update
+its status line. Mark the workstream complete in this index once all
+sub-items are done.