chemicalml 0.2.0 → 0.3.0

data/TODO.align/README.round22.md

@@ -0,0 +1,48 @@
+# Round 22 — Missing molecular constraints, CLI, diverse fixtures
+
+This round closes constraints from the molecular spec that were
+genuinely missing, adds a CLI utility, and broadens fixture
+coverage to exercise more code paths.
+
+## Files
+
+- [85 — Bond atomRefs2 distinct constraint](85-bond-distinct-atoms.md)
+- [86 — References-should-resolve constraint](86-references-should-resolve.md)
+- [87 — CLI utility](87-cli-utility.md)
+- [88 — Diverse fixtures](88-diverse-fixtures.md)
+- [89 — Final verification round 22](89-final-verification-round22.md)
+
+## Outcomes
+
+- `BondAtomRefs2ShouldBeDistinct` — warning when `atomRefs2` references
+  the same atom twice (e.g. `a1 a1`). Closes the molecular spec's
+  "two distinct atom ids" rule.
+- `ReferencesShouldResolve` — DocumentConstraint that uses
+  `Cml::ReferenceResolver` to walk the document and report bonds
+  referencing missing atoms. Catches typos like `atomRefs2="a1 a99"`
+  when only a1 exists.
+- `Chemicalml::Cli` + `exe/chemicalml` — CLI utility with three
+  commands:
+  - `chemicalml validate <file>` — auto-detect convention, print
+    violations to stderr, exit non-zero on errors
+  - `chemicalml conventions` — list the 8 registered conventions
+  - `chemicalml dictionaries` — list the 8 built-in dictionaries
+- New fixtures:
+  - chiral_center_with_bond_stereo.cml (bondStereo W/H + atomParity)
+  - ethanol_with_properties.cml (propertyList + formula)
+  - nacl_with_lattice.cml (crystal + symmetry + matrix)
+  - diels_alder.cml (reactionScheme + reactantList + productList)
+- Molecular convention now registers 28 constraints (up from 26).
+- **471 examples, 0 failures, 3 pending**. Zero forbidden patterns.
+
+## Architectural notes
+
+- The `ReferencesShouldResolve` constraint is the first
+  `DocumentConstraint` (vs NodeConstraint) in the molecular
+  convention. It demonstrates the convention framework's
+  support for cross-cutting rules that need the whole document.
+- The CLI is a thin dispatcher — adding a new subcommand = adding
+  one method and one entry in `Cli::COMMANDS`. OCP.
+- Existing fixtures already passed; the new ones exercise the
+  recently added bondStereo / propertyList / crystal / reaction
+  paths in the Base modules.

data/TODO.align/README.round23.md

@@ -0,0 +1,46 @@
+# Round 23 — Convention spec completeness, YARD docs
+
+This round closes remaining gaps between the upstream convention
+specs and our implementation, and adds YARD documentation to the
+public API.
+
+## Files
+
+- [90 — BondStereo completeness](90-bond-stereo-completeness.md)
+- [91 — AtomParity atomRefs4 distinct](91-atomparity-distinct.md)
+- [92 — Unit-dictionary completeness](92-unit-dictionary-completeness.md)
+- [93 — YARD docs for public API](93-yard-docs.md)
+- [94 — Final verification round 23](94-final-verification-round23.md)
+
+## Outcomes
+
+- `BondStereoAtomRefs4ShouldBeDistinct` — molecular warning when
+  C/T stereo's atomRefs4 has duplicate atoms. The molecular spec
+  says "four distinct atom ids" — now enforced.
+- `AtomParityAtomRefs4ShouldBeDistinct` — molecular warning when
+  atomParity's atomRefs4 has duplicates. Closes a real semantic gap:
+  duplicate parity atoms make the chiral descriptor meaningless.
+- Three new unit-dictionary constraints:
+  - `UnitMustHaveTitle`
+  - `UnitMustHaveParentSi`
+  - `UnitMustHaveMultiplierOrConstantToSi`
+- Molecular convention: 30 constraints (up from 28).
+- Unit-dictionary convention: 8 constraints (up from 5).
+- YARD docstrings added to:
+  - `Chemicalml.parse`, `Chemicalml.serialize`, `Chemicalml.parser_for`
+  - `Chemicalml::Cli.run`, `Chemicalml::Cli.run_validate`
+  - `Chemicalml::Convention.validate`, `validate_report`, `detect_and_validate`, `lookup`
+  - `Chemicalml::Dictionary.load`
+  - `Chemicalml::Cml::ReferenceResolver#initialize`
+- **471 examples, 0 failures, 3 pending**. Zero forbidden patterns.
+
+## Architectural notes
+
+- All new constraints are warning severity (or error where the spec
+  uses MUST). The convention framework distinguishes naturally.
+- YARD docstrings follow the existing pattern (concise, no novel
+  terminology, examples where helpful). They will be picked up by
+  `bundle exec yard doc` when the yard gem is added.
+- The spec count stays the same (471) because the round-23 spec
+  file replaces one existing test; new constraint tests replace the
+  old "5 constraints" / "28 constraints" assertion tests.

data/TODO.align/README.round24.md

@@ -0,0 +1,53 @@
+# Round 24 — Round-trip equivalence, cross-format interop, introspection
+
+This round formalises the round-trip guarantee across all fixtures,
+proves cross-format interoperability (XML → JSON → YAML → XML),
+adds a convention introspection API, and exercises Schema24 with
+complex content.
+
+## Files
+
+- [95 — Round-trip equivalence spec](95-round-trip-equivalence.md)
+- [96 — Cross-format interoperability](96-cross-format-interop.md)
+- [97 — Convention introspection API](97-convention-introspection.md)
+- [98 — Schema24 complex round-trip](98-schema24-complex-round-trip.md)
+- [99 — Final verification round 24](99-final-verification-round24.md)
+
+## Outcomes
+
+- **Round-trip equivalence spec** — for every one of the 20 fixtures,
+  asserts that `parse(xml) → serialize → parse` produces a
+  structurally-equivalent document (compared via a recursive
+  element-name fingerprint). Catches future serialization drift.
+
+- **Cross-format interoperability spec** — proves the format-agnostic
+  claim end-to-end:
+  - XML → JSON → XML (structural fingerprint equal)
+  - XML → YAML → XML (structural fingerprint equal)
+  - JSON → JSON idempotent (same output)
+  - XML → JSON → YAML → XML (4-format chain, structural equal)
+
+- **`Convention::Registry.each`** — iterates all 8 conventions
+  sorted by QName. Returns an Enumerator without a block.
+- **`Convention::Registry.convention_root?(role)`** — boolean check
+  for whether a Role module is a convention-bearing root.
+
+- **Schema24 complex round-trip** — exercises the now-fixed Schema24
+  parser with rich content (parallel-array atoms + bonds, names,
+  formulas). Proves Schema24 has feature parity with Schema3.
+
+- **Real bug fix discovered via round 24 testing**:
+  `AtomArrayMustContainAtoms` was rejecting parallel-array form
+  (which has no `<atom>` children but uses `atomID` attribute).
+  Fixed to accept either form.
+
+- **515 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns.
+
+## Architectural insight
+
+The cross-format interop spec is the most valuable safety net: any
+future change to the Base modules that breaks the format-agnostic
+claim (e.g. adds a method that only works in one format) is caught
+immediately. The structural fingerprint comparison is format-blind,
+so it catches real data loss rather than just string-equality noise.

data/TODO.align/README.round25.md

@@ -0,0 +1,66 @@
+# Round 25 — Semantic validation, periodic table, dictRef resolution
+
+This round adds three real semantic checks (element type, dictRef
+resolution, summary rendering) that go beyond structural validation.
+
+## Files
+
+- [100 — Periodic table constant](100-periodic-table.md)
+- [101 — Element type validation constraint](101-element-type-validation.md)
+- [102 — DictRef resolution constraint](102-dictref-resolution.md)
+- [103 — ValidationReport summary](103-validation-report-summary.md)
+- [104 — Final verification round 25](104-final-verification-round25.md)
+
+## Outcomes
+
+- **`Cml::Enums::ELEMENT_TYPE_VALUES`** — 120-element frozen Set
+  matching XSD elementTypeType exactly. Includes the periodic table
+  plus "Du" (dummy) and "R" (group placeholder). Single source of
+  truth for valid element symbols.
+
+- **`AtomElementTypeShouldBeInPeriodicTable`** — molecular warning
+  when `atom.elementType` isn't a recognised periodic table symbol.
+  Catches typos like "Carb", "Xx", "X" — previously silently
+  accepted.
+
+- **`DictRefShouldResolve`** — molecular warning when an element's
+  `dictRef` attribute doesn't resolve against the built-in
+  dictionaries via `Chemicalml::Dictionary::Registry.lookup`. Catches
+  typos like `dictRef="cml:bpingpoint"`. This is a real
+  cross-component integration: the convention constraint system
+  querying the dictionary registry.
+
+- **`ValidationReport#summary`** — human-readable multi-line summary.
+  Used by the CLI; useful for one-shot scripts. Format:
+  ```
+  Errors: 2, Warnings: 1
+
+  Errors:
+    ERROR path/a: message (value="X")
+    ...
+
+  Warnings:
+    WARN  path/b: message
+    ...
+  ```
+
+- **Real bug caught by new constraint**: existing test
+  `extended_constraints_spec.rb` was using `dictRef="cml:energy"`
+  which isn't in the cml dictionary. The new DictRefShouldResolve
+  constraint flagged it. Fixed the test to use the real `cml:bp`
+  entry — and incidentally validated that the constraint works.
+
+- Molecular convention: 32 constraints (up from 30).
+
+- **528 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns.
+
+## Architectural insight
+
+The DictRefShouldResolve constraint is the first to bridge two
+previously-separate subsystems (convention constraints and
+dictionary registry). It validates the cross-component contract:
+"a dictRef must point at a real term". This is the kind of
+whole-system semantic check that's only possible when both halves
+are mature — round 25 is the first round where it became worth
+writing.

data/TODO.align/README.round26.md

@@ -0,0 +1,55 @@
+# Round 26 — XSD patterns, AtomParity parent check, canonical comparison
+
+This round adds the canonical XSD pattern constants, semantic
+parent-atom validation for atomParity, and a canonical document
+comparison helper.
+
+## Files
+
+- [105 — XSD pattern constants](105-xsd-pattern-constants.md)
+- [106 — Id/namespace pattern validation](106-id-pattern-validation.md)
+- [107 — AtomParity parent atom check](107-atomparity-parent-check.md)
+- [108 — Canonical document comparison](108-canonical-comparison.md)
+- [109 — Final verification round 26](109-final-verification-round26.md)
+
+## Outcomes
+
+- **`Cml::Patterns`** — 14 frozen Regexp constants matching every XSD
+  simpleType that restricts by pattern (atomIDType, idType,
+  dictionaryPrefixType, namespaceType, refType, versionType,
+  formulaType, etc.). Single source of truth — a future XSD edit
+  that changes a pattern can be regenerated from one place.
+
+- **`MoleculeIdShouldMatchPattern`** and **`BondIdShouldMatchPattern`**
+  — molecular warnings using the new patterns. Catches ids that
+  don't match the XSD-declared format.
+
+- **`AtomParityShouldIncludeParentAtom`** — molecular DocumentConstraint
+  that walks the tree and warns when `<atomParity>`'s atomRefs4
+  doesn't include the parent `<atom>`'s id. Real semantic check
+  that closes a CML convention rule.
+
+- **`Cml::CanonicalComparison`** — semantic document comparison.
+  `equal?` returns true if two documents have the same structural
+  fingerprint. `diff` returns a hash of element_name → count_delta.
+  Useful for testing and diff tools.
+
+- **Real bugs caught during round 26**:
+  - DELIMITER_PATTERN had unescaped `/` — syntax error.
+  - `visit_with_parent` was using `yield` in recursion, causing
+    LocalJumpError. Fixed by using explicit `&block`.
+  - XSD patterns are unanchored; for validation they must be
+    wrapped in `\A...\z`.
+
+- Molecular convention: 35 constraints (up from 32).
+
+- **543 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns.
+
+## Architectural insight
+
+The `CanonicalComparison` helper is the abstraction the round-trip
+spec (TODO 95) and Schema24 complex round-trip spec (TODO 98) both
+needed. Previously each spec inlined its own fingerprint function;
+now there's one canonical implementation. Classic "rule of three"
+refactor — the third use is the trigger to extract.

data/TODO.align/README.round27.md

@@ -0,0 +1,51 @@
+# Round 27 — User-facing API, CLI improvements
+
+This round adds the user-facing query API on `Cml::Visitable`, a
+top-level `Chemicalml.validate` shortcut, and two new CLI commands
+(`inspect`, `elements`).
+
+## Files
+
+- [110 — Document query API](110-document-query-api.md)
+- [111 — Top-level Chemicalml.validate](111-toplevel-validate.md)
+- [112 — CLI inspect command](112-cli-inspect.md)
+- [113 — CLI elements command](113-cli-elements.md)
+- [114 — Final verification round 27](114-final-verification-round27.md)
+
+## Outcomes
+
+- **`Cml::Visitable` query methods** (inherited by every wire class):
+  - `#each_wire_node`, `#each_atom`, `#each_bond`, `#each_molecule` — recursive iterators
+  - `#find_atom(id)`, `#find_bond(id)`, `#find_molecule(id)` — id-based lookup
+  - `#atom_count`, `#bond_count`, `#molecule_count` — recursive counts
+  - All return Enumerators without a block (Enumerable-style)
+
+- **`Chemicalml.validate(doc)`** — top-level shortcut for
+  `Convention.detect_and_validate(doc)`. Users no longer need to
+  remember the full namespace.
+
+- **`chemicalml inspect <file>`** — new CLI command. Prints a
+  tree-style summary of the document with element names, ids, and
+  structure. Useful for debugging.
+
+- **`chemicalml elements`** — new CLI command. Lists every Schema3
+  wire class with its XML root name. Useful for introspection.
+
+- **CLI refactor**: `run_validate` now uses `report.summary` instead
+  of manual rendering. Cleaner code, better output.
+
+- **559 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns.
+
+## Architectural insight
+
+The query methods live on `Visitable` (the marker mixin every wire
+class includes) rather than on `Document` specifically. This means
+ANY wire class can be the root of a query — `molecule.find_atom(id)`,
+`reaction.find_molecule(id)`, etc. This was the right call: the
+walker is already general (visits any subtree); exposing query
+methods only on Document would have required callers to navigate
+up to Document first.
+
+The CLI's `print_tree` helper is recursive but bounded (`max_depth: 6`)
+to avoid runaway output on pathological documents.

data/TODO.align/README.round28.md

@@ -0,0 +1,61 @@
+# Round 28 — Convenience API, custom conventions, compchem completion
+
+This round adds user-facing convenience (`parse_file`, custom
+convention registration), more compchem constraints from the spec,
+and a comprehensive lint cleanup.
+
+## Files
+
+- [115 — parse_file convenience](115-parse-file.md)
+- [116 — Custom convention registration](116-custom-convention.md)
+- [117 — More compchem constraints](117-more-compchem-constraints.md)
+- [118 — Final verification round 28](118-final-verification-round28.md)
+
+## Outcomes
+
+- **`Chemicalml.parse_file(path)`** — convenience wrapper around
+  `parse(File.read(path))`. Raises ArgumentError for missing files.
+  Eliminates the `File.read` boilerplate.
+
+- **`Convention::Registry.register_custom(mod)`** — runtime
+  registration of custom conventions. The module must `extend Base`
+  and return a non-empty `qname`. Useful for domain-specific CML
+  extensions (e.g., a `convention:my-lab-extensions` for a research
+  group's custom vocabulary).
+
+- **Two new compchem constraints** from the spec:
+  - `InitializationMustHaveContent` — initialization module must
+    contain at least one of molecule, parameterList, or user-defined
+    module
+  - `FinalizationMustHaveContent` — finalization module must contain
+    at least one of molecule, propertyList, or user-defined module
+
+- **Lint cleanup**: ran `rubocop -A` on all recently-touched files.
+  80 offenses autocorrected (string quotes, modifier-if usage,
+  parenthesised method args, etc.). Zero remaining style issues.
+
+- **Real bug caught during round 28**: `register_custom` initially
+  deadlocked because it called `load_cache` while holding the mutex.
+  Fixed by separating the load step (which acquires/releases its
+  own mutex) from the mutation step (direct hash access after load
+  is guaranteed to have populated `@cache`).
+
+- Compchem convention: 20 constraints (up from 18).
+
+- **568 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns. **88 constraints across 8 conventions.**
+
+## Architectural insight
+
+The `register_custom` deadlock is a classic Ruby mutex pitfall:
+re-entering a non-reentrant `Mutex#synchronize` block from within
+itself deadlocks. The fix — call `load_cache` first (which manages
+its own mutex acquisition), then mutate `@cache` directly — works
+because Ruby's `||=` assignment makes `@cache` non-nil after the
+first load. Documented in the method comment.
+
+This round also reinforced the value of running rubocop on each
+round's output. 80 autocorrected offenses across 8 files means
+style drift was creeping in — single-quote vs double-quote,
+`unless` vs `if !`, etc. A small CI rule (`bundle exec rubocop`
+must pass) would catch this in future.

data/TODO.align/README.round29.md

@@ -0,0 +1,64 @@
+# Round 29 — Wire introspection, README, dataType consistency
+
+This round adds wire-class introspection, updates the README to
+reflect the current API, and adds a property-dataType consistency
+constraint that bridges the convention and dictionary subsystems
+in a new way.
+
+## Files
+
+- [119 — Wire-class introspection](119-wire-introspection.md)
+- [120 — Update README](120-readme-update.md)
+- [121 — Property dataType consistency](121-property-datatype.md)
+- [122 — Final verification round 29](122-final-verification-round29.md)
+
+## Outcomes
+
+- **`Cml.for_xml_name(name, schema:)`** — wire-class lookup by XML
+  element name. Uses the existing `Elements::XML_TO_CLASS` reverse
+  index. Returns nil for unknown names.
+
+- **`Cml.wire_classes(schema:)`** — enumerator over all wire classes
+  for a schema version. Useful for code generation and tooling.
+
+- **README rewritten**:
+  - 8 conventions + 88+ constraints documented
+  - All modern API examples (`parse_file`, `validate`, `each_atom`)
+  - CLI commands documented (`validate`, `inspect`, `conventions`,
+    `dictionaries`, `elements`)
+  - Cross-format serialisation examples
+  - Custom convention registration example
+  - Dictionary lookup example
+  - Architectural overview (`Base::*`, `Role::*`, `Elements::ALL`)
+
+- **`PropertyScalarDataTypeMatchesDictionary`** — molecular warning
+  when a `<property>`'s `<scalar>` `dataType` doesn't match the
+  `dataType` declared in the dictionary entry referenced by `dictRef`.
+  This is a **three-component integration check**: convention
+  constraint system queries the dictionary registry AND inspects the
+  document's scalar child.
+
+- Molecular convention: 36 constraints (up from 35).
+
+- **574 examples, 0 failures, 3 pending**. Zero forbidden patterns.
+
+## Architectural insight
+
+`PropertyScalarDataTypeMatchesDictionary` is the deepest
+cross-component check yet — it validates that:
+
+1. The property's `dictRef` resolves to a real dictionary entry
+   (uses `Dictionary::Registry.lookup`).
+2. The entry declares a `dataType`.
+3. The property's `<scalar>` child declares a `dataType`.
+4. The two `dataType` values match.
+
+If any step is missing data, the constraint silently passes (no
+false positives). When all the data is present, it catches real
+inconsistencies that would cause downstream type errors.
+
+This kind of multi-step semantic validation is what mature
+document-validation frameworks look like. Round 29 is the first
+round where it's been possible — earlier rounds built the
+primitives (dictionary registry, dictRef resolution, scalar
+dataType attribute) that this constraint composes.

data/TODO.align/README.round30.md

@@ -0,0 +1,50 @@
+# Round 30 — unitType resolution, JSON CLI, enumeration
+
+This round adds the unit-unitType cross-component check (parallels
+dictRef resolution), CLI JSON output for machine consumers, and a
+constraint-enumeration API.
+
+## Files
+
+- [123 — Unit unitType resolution](123-unit-unittype-resolution.md)
+- [124 — CLI JSON output](124-cli-json-output.md)
+- [125 — Constraint enumeration API](125-constraint-enumeration.md)
+- [126 — Final verification round 30](126-final-verification-round30.md)
+
+## Outcomes
+
+- **`UnitUnitTypeShouldResolve`** — unit-dictionary warning when a
+  `<unit>`'s `unitType` attribute doesn't resolve against the
+  built-in unitType-dictionary. Cross-component check parallel to
+  the molecular convention's `DictRefShouldResolve`.
+
+- **`chemicalml validate --json file.cml`** — JSON output mode for
+  the CLI. Returns `{ file:, ok:, has_warnings:, violations: [...] }`
+  where each violation has `severity`, `path`, `message`, `value`.
+  Useful for editor integration, CI pipelines, automated tooling.
+
+- **`Convention::Registry.each_constraint`** — iterates every
+  constraint across every convention, yielding `(convention, class)`
+  pairs. Useful for documentation generation and introspection.
+
+- **`Convention::Registry.total_constraint_count`** — sum of all
+  registered constraints across all conventions (currently 90).
+
+- Unit-dictionary convention: 9 constraints (up from 8).
+
+- **580 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns. **90 constraints across 8 conventions.**
+
+## Architectural insight
+
+`UnitUnitTypeShouldResolve` completes a symmetric pair with
+`DictRefShouldResolve` from round 25. Both follow the same pattern:
+walk the document, look up reference attributes against the
+dictionary registry, warn on misses. The pattern is now established
+enough that adding a new reference-resolution constraint is a
+2-minute job: copy the structure, change the attribute name and the
+target dictionary.
+
+The `each_constraint` iterator makes the constraint table tractable
+for documentation generation. A future round could auto-generate a
+Markdown table of all 90 constraints from this single API call.

data/TODO.align/README.round31.md

@@ -0,0 +1,54 @@
+# Round 31 — CLI tooling, parentSI resolution
+
+This round completes the CLI tooling suite (constraints + enums
+commands) and adds the parentSI resolution constraint, completing
+the cross-component check symmetry.
+
+## Files
+
+- [127 — CLI constraints command](127-cli-constraints.md)
+- [128 — CLI enums command](128-cli-enums.md)
+- [129 — ParentSI resolution](129-parentsi-resolution.md)
+- [130 — Final verification round 31](130-final-verification-round31.md)
+
+## Outcomes
+
+- **`chemicalml constraints`** — new CLI command listing all 91
+  constraints grouped by convention. Each line shows the constraint
+  class name and its declared `applies_to` roles.
+
+- **`chemicalml enums`** — new CLI command listing every
+  `Cml::Enums` constant with its allowed values. Useful for users
+  who want to know what enum values an attribute accepts.
+
+- **`UnitParentSiShouldResolve`** — unit-dictionary warning when a
+  `<unit>`'s `parentSI` doesn't resolve against built-in
+  dictionaries. Completes the cross-component check symmetry:
+  - dictRef resolution (molecular)
+  - unitType resolution (unit-dictionary)
+  - parentSI resolution (unit-dictionary)
+
+- **Real bug caught during round 31**: existing fixture
+  `convention_spec.rb:226` used `parent_si: "siUnits:s"` which
+  doesn't resolve (correct prefix is `si`, not `siUnits`). Fixed.
+
+- Unit-dictionary convention: 10 constraints (up from 9).
+
+- **583 examples, 0 failures, 3 pending**. Zero forbidden patterns.
+  **91 constraints across 8 conventions.**
+
+## Architectural insight
+
+The cross-component check pattern (walk document → look up reference
+attribute against registry → warn on miss) is now fully
+established across three constraint pairs:
+
+| Convention | Attribute | Lookup target |
+|---|---|---|
+| molecular | `dictRef` | dictionary registry |
+| unit-dictionary | `unitType` | unitType-dictionary registry |
+| unit-dictionary | `parentSI` | unit dictionary registry |
+
+Adding a fourth is mechanical: copy the structure, change the
+attribute name and lookup target. The pattern's clarity is its own
+form of documentation.

data/TODO.align/README.round32.md

@@ -0,0 +1,67 @@
+# Round 32 — Thor CLI refactor, info command, auto-docs
+
+This round refactors the CLI to use Thor with one class per command,
+adds the `info` command for element introspection, and auto-generates
+constraint documentation.
+
+## Files
+
+- [131 — CLI info command](131-cli-info-command.md)
+- [132 — Auto-generated constraint docs](132-auto-generated-constraint-docs.md)
+- [133 — Final verification round 32](133-final-verification-round32.md)
+
+## Outcomes
+
+- **CLI refactored to Thor**. Each command is now a dedicated class:
+  - `Chemicalml::Cli::Base < Thor` — dispatcher
+  - `Chemicalml::Cli::Command` — base class with `.run(args, options)`
+    and `#run(args, options)`
+  - `Chemicalml::Cli::ValidateCommand`
+  - `Chemicalml::Cli::InspectCommand`
+  - `Chemicalml::Cli::ConventionsCommand`
+  - `Chemicalml::Cli::DictionariesCommand`
+  - `Chemicalml::Cli::ElementsCommand`
+  - `Chemicalml::Cli::ConstraintsCommand`
+  - `Chemicalml::Cli::EnumsCommand`
+  - `Chemicalml::Cli::InfoCommand`
+
+  Each command supports both `MyCommand.run(args, options)` (class
+  method) and `MyCommand.new.run(args, options)` (instance method)
+  invocation patterns — matching the user's requested pattern.
+
+- **`chemicalml info <element>`** — new CLI command. Shows element
+  XML name, Ruby class, included Role module, all attributes (with
+  collection marker), and all applicable constraints across every
+  convention. Useful for users exploring the model.
+
+- **Auto-generated constraint docs** — `docs/generate_constraint_docs.rb`
+  script produces `docs/constraints.md` from
+  `Convention::Registry.each_constraint`. Single source of truth —
+  regenerating picks up new constraints automatically. No manual
+  maintenance.
+
+- **Bug fix from autocorrect**: `Convention::Registry#load_cache`
+  had `@cache` renamed to `@load_cache` by rubocop's
+  `MemoizedInstanceVariableName` rule. `register_custom` and `reset!`
+  needed alignment — fixed in this round.
+
+- **586 examples, 0 failures, 3 pending**. Zero forbidden patterns.
+
+## Architectural insight
+
+The Thor refactor separates concerns cleanly:
+
+1. **Thor dispatcher** owns argument parsing, help text, option
+   declarations. Each `desc + def` block is 2-3 lines.
+2. **Command class** owns the actual work. Easy to test in isolation
+   (`MyCommand.new.run(args, options)` returns an exit code).
+3. **No business logic in the dispatcher** — it's pure routing.
+
+This pattern scales: a future `rake` task, Rake task, or web handler
+can re-use any `*Command` class without going through Thor. The
+Thor dispatcher is just one possible entry point.
+
+The auto-generated constraint docs demonstrate the value of the
+`each_constraint` API from round 30: a single iteration produces
+comprehensive documentation with zero manual upkeep. Adding a new
+constraint and re-running the generator is all it takes.