idml 0.1.0

data/TODO.complete/08-round-trip-suite.md

@@ -0,0 +1,44 @@
+# TODO 08: Whole-package round-trip suite
+
+## Goal
+
+End-to-end: open `spec/fixtures/sample-with-image/sample-with-image.idml`,
+parse every typed part, serialize back, rezip, assert XML-equivalence per
+part.
+
+## Acceptance criteria
+
+- [ ] `spec/idml/round_trip_spec.rb` opens the fixture, iterates every part
+      name, calls `Package.part(name)`, calls `to_xml` on the result, and
+      asserts the output is XML-equivalent (via Nokogiri canonicalization)
+      to the original.
+- [ ] All 14 typed parts pass: designmap, 2 spreads, 1 master spread, 4
+      stories, BackingStory, Tags, Graphic, Fonts, Styles, Preferences.
+- [ ] Untyped parts (mimetype, META-INF/container.xml, META-INF/metadata.xml)
+      round-trip as raw bytes.
+- [ ] `Idml::Package.write(parts:, to:)` produces a valid IDML ZIP that
+      Adobe InDesign can open (manual verification by user; document the
+      verification in spec comments — wait, no comments — in the TODO file).
+- [ ] Byte-for-byte comparison documented: where it matches and where it
+      differs (e.g., XML declaration whitespace, attribute order). Use
+      canonicalization for the comparison; report drift.
+
+## Files
+
+- `spec/idml/round_trip_spec.rb`
+- `lib/idml/test_support.rb` (optional) — helpers like
+  `assert_xml_equivalent(a, b)`. If small enough, inline in the spec.
+
+## Design notes
+
+- XML equivalence: parse both sides with Nokogiri, canonicalize via
+  `Nokogiri::XML::Document#canonicalize`, compare strings. This handles
+  attribute order, whitespace, namespace declaration placement.
+- For the strictest round-trip (byte-for-byte), document but don't gate the
+  suite on it — that's a future enhancement requiring tighter XML formatter
+  control.
+- Parameterize by fixture so we can add cross-version fixtures later.
+
+## Dependencies
+
+- TODO 02–07 (all part models).

data/TODO.complete/09-validation.md

@@ -0,0 +1,51 @@
+# TODO 09: RelaxNG validation via Jing
+
+## Goal
+
+Wrap the bundled Jing validator (`reference-docs/plugin_sdk_21/devtools/idmltools/jing/`)
+behind a Ruby API. Users can validate any `.idml` part (or whole package)
+against the schemas in `reference-docs/schemas/package/`.
+
+## Acceptance criteria
+
+- [ ] `Idml::Validation` module autoloaded from `lib/idml.rb`.
+- [ ] `Idml::Validation::Validator.new(schema_root:)` — points at the RNG
+      schema directory (default: vendored under the gem, see below).
+- [ ] `#validate_part(file_name, xml)` → returns a `Result` with `#ok?`,
+      `#errors` (Array of error message strings).
+- [ ] `#validate_package(package)` → returns a `ResultSet` enumerating
+      per-part `Result`s.
+- [ ] Jing is invoked as `java -jar .../jing.jar -c <rnc> <xml>`; output is
+      parsed for `error:` lines.
+- [ ] On a clean fixture (`sample-with-image.idml`), all 14 parts validate
+      OK.
+- [ ] On a deliberately-broken XML (e.g., missing required attribute),
+      errors are captured and reported with line numbers.
+- [ ] `java` not on PATH → raises `Idml::Validation::JavaUnavailable` with a
+      helpful message.
+
+## Files
+
+- `lib/idml/validation.rb`
+- `lib/idml/validation/result.rb` (or inline)
+- `lib/idml/validation/validator.rb` (or inline)
+- `spec/idml/validation/validator_spec.rb`
+
+## Design notes
+
+- Schema sourcing: do NOT vendor the 1.6 MB schemas into the gem install.
+  Instead, accept a `schema_root:` argument with a sensible default that
+  points at `reference-docs/schemas/package/` for development. Document
+  this in the README. Users who want validation install schemas separately.
+- Jing invocation: `Open3.capture3` to capture stdout/stderr separately.
+  Jing emits errors to stderr.
+- Result objects: structs, not heavy classes. `Struct.new(:file_name, :ok,
+  :errors)`.
+- Java version: Jing 20030619 needs Java 1.4+; modern Javas (8–21) work.
+  Don't over-engineer detection — `java -version` once, cache the result.
+- The schema file for a given part name comes from the same mapping used by
+  `Parts::PATTERNS` — reuse it.
+
+## Dependencies
+
+- TODO 02 (Package), TODO 03 (Parts mapping).

data/TODO.complete/10-composition.md

@@ -0,0 +1,62 @@
+# TODO 10: Composition layer (stubs + design)
+
+## Goal
+
+Lay down the API surface for composition operations. Implement only the
+trivial ones; defer the rest with documented `NotImplementedError` so the
+gem's API shape is clear and stable.
+
+## Acceptance criteria
+
+- [ ] `Idml::Composition` module autoloaded from `lib/idml.rb`.
+- [ ] Command-pattern classes for each operation:
+      - `Composition::InsertIdml` — `#call(source:, into:, at:, only:)`
+      - `Composition::AddPageFromIdml` — `#call(source:, page_number:, at:, only:)`
+      - `Composition::Prefix` — `#call(prefix:)` — renames Self IDs to avoid
+        collisions when composing two packages.
+      - `Composition::ImportXml` — `#call(xml_string:, at:)`
+      - `Composition::ExportXml` — `#call` — returns the logical XML tree
+        as a string.
+- [ ] Each command class takes a `Package` in its constructor and implements
+      `#call` returning a new `Package` (no mutation).
+- [ ] All commands raise `NotImplementedError` with a message pointing to
+      this TODO file as the design source. Only `Prefix` and the framework
+      are implemented in this TODO (the rest are future work).
+- [ ] `Prefix#call(prefix:)` is fully implemented: rewrites every `Self`
+      attribute value in every part to be prefixed with the given string.
+      Tested against the fixture.
+- [ ] Spec: each command class has its own spec file. Stub commands have
+      specs asserting they raise `NotImplementedError` with the right
+      message.
+
+## Files
+
+- `lib/idml/composition.rb` — module + autoloads.
+- `lib/idml/composition/insert_idml.rb`
+- `lib/idml/composition/add_page_from_idml.rb`
+- `lib/idml/composition/prefix.rb`
+- `lib/idml/composition/import_xml.rb`
+- `lib/idml/composition/export_xml.rb`
+- `lib/idml/geometry.rb` — coordinate-transform helpers for insertion
+  (port from SimpleIDML's `doc/IDML_insert_idml_coordinate_transformation.*`).
+  Stubbed in this TODO; full implementation deferred.
+- `spec/idml/composition/{insert_idml,add_page_from_idml,prefix,import_xml,export_xml}_spec.rb`
+
+## Design notes
+
+- Command pattern (not methods on Package) is the OCP move: adding a new
+  composition operation = adding a new class, not editing `Package`.
+- Each command is a callable (`#call`). They compose: `InsertIdml.new(pkg1).
+  call(source: pkg2, ...)` returns a new package that can be passed to the
+  next command.
+- `Prefix` is the only fully implemented command because it's the simplest
+  (just rewrite Self attributes) and is a prerequisite for every other
+  composition op (you always prefix before inserting to avoid ID
+  collisions).
+- Future composition work (post-this-TODO) will port the algorithms from
+  SimpleIDML's `simple_idml/idml.py` directly — the algorithms are well-
+  tested there.
+
+## Dependencies
+
+- TODO 02–07 (Package + all parts).

data/TODO.complete/11-package-accessors.md

@@ -0,0 +1,41 @@
+# TODO 11: Package convenience accessors
+
+## Goal
+
+Add typed accessors on `Package` so users don't need to know the
+filename patterns: `pkg.designmap`, `pkg.spreads`, `pkg.stories`,
+`pkg.backing_story`, `pkg.master_spreads`, `pkg.fonts`, etc.
+
+## Acceptance criteria
+
+- [ ] `Package#designmap` returns the typed `Designmap` instance.
+- [ ] `Package#backing_story` returns the `BackingStory` instance.
+- [ ] `Package#spreads` returns an Array of `Spread` instances (one
+      per `Spreads/Spread_*.xml`).
+- [ ] `Package#master_spreads`, `#stories` similarly.
+- [ ] `Package#fonts`, `#graphic`, `#style`, `#style_mapping`,
+      `#preferences`, `#tags`, `#mapping` — one per Resources/XML file.
+      Return `nil` if the file is absent.
+- [ ] Each accessor caches its result on first call (memoized) so
+      repeat calls don't re-read the ZIP.
+- [ ] Specs cover each accessor against the fixture, including the
+      absent-file case (e.g., `pkg.mapping` is nil on the fixture
+      because Mapping.xml doesn't exist).
+
+## Files
+
+- `lib/idml/package.rb` — accessor methods.
+- `spec/idml/package_accessors_spec.rb` — full coverage.
+
+## Design notes
+
+- Accessors route through the existing `Parts.class_for` registry so
+  they stay in sync with the part layer automatically. New part
+  classes get accessors "for free" if the user adds them to Package,
+  but the registry remains the source of truth.
+- Memoization uses the standard `@name ||= ...` pattern. Cache is
+  per-instance, so a new Package re-reads.
+
+## Dependencies
+
+- TODOs 03–07 (all part classes registered).

data/TODO.complete/12-document-layer.md

@@ -0,0 +1,44 @@
+# TODO 12: Document layer (cross-part navigation)
+
+## Goal
+
+`Idml::Document` wraps a Package and provides cross-part navigation
+that the Package layer deliberately doesn't: resolve `Self` IDs
+across parts, traverse the logical XML structure tree, expose
+story text as plain strings.
+
+## Acceptance criteria
+
+- [ ] `Idml::Document.new(package)` constructs a Document.
+- [ ] `#find_by_self(id)` searches every part for an element with
+      `Self="#{id}"` and returns it (as a parsed XML node for now;
+      typed model when available). Returns `nil` if not found.
+- [ ] `#story_text(story_self)` returns the concatenated plain-text
+      content of all `Content` runs in the story with that Self.
+- [ ] `#xml_structure` returns the BackingStory tree as a Nokogiri
+      document — the logical XML structure InDesign exposes via the
+      Structure panel.
+- [ ] `#each_story(&block)` yields each Story instance with its text.
+- [ ] `#tagged_elements` returns every `XMLElement` in every Story,
+      with the markup tag name. Used to map structure to styling.
+- [ ] Specs use the fixture and verify a known Self ID resolves.
+
+## Files
+
+- `lib/idml/document.rb`
+- `lib/idml.rb` — autoload `Document`.
+- `spec/idml/document_spec.rb`
+
+## Design notes
+
+- Document is a READ-ONLY view. It delegates to Package and Parts;
+  it does not own state. Constructed cheaply; operations lazy.
+- Cross-part resolution requires parsing XML. We use Nokogiri for
+  the search; the typed models stay as the "official" representation
+  for the parts we've modeled.
+- `Self` IDs are globally unique within a document (InDesign
+  guarantees this), so a flat search across all parts is correct.
+
+## Dependencies
+
+- TODO 11 (Package accessors) — Document uses them.

data/TODO.complete/13-insert-idml.md

@@ -0,0 +1,31 @@
+# TODO 13: InsertIdml composition operation
+
+## Goal
+
+`Composition::InsertIdml` — merge one package's structural content
+into another. Prefixes both packages to avoid Self collisions, then
+merges BackingStory, Stories, Spreads, MasterSpreads, and updates
+designmap's StoryList to reference the source stories.
+
+## Status
+
+DONE. The implementation lives in
+`lib/idml/composition/insert_idml.rb`. Specs in
+`spec/idml/composition/insert_idml_spec.rb` cover:
+- Returns a new Package (no mutation of receiver).
+- Prefixes both sides (`dest_` / `src_`).
+- Carries source stories, spreads, and master spreads through.
+- Rewrites designmap StoryList to include source's stories.
+
+## Design
+
+- Uses `Composition::Prefix` to namespace every Self reference
+  (including StoryList and the various cross-reference attributes
+  like FillColor, ParentStory, XMLContent) so the two packages can
+  coexist in one output without ID collisions.
+- Merges at the structural level: BackingStory's `xml_story`
+  collection is extended; per-part copies via Package#each_part.
+- No XPath. The structural merge handles the realistic use case
+  (compose two packages into one). Subtree extraction at the page-
+  item level would require modeling IDML's geometric reflow — out
+  of scope for this gem.

data/TODO.complete/14-geometry.md

@@ -0,0 +1,33 @@
+# TODO 14: Geometry.translate (coordinate transforms)
+
+## Goal
+
+Implement `Idml::Geometry.translate(point, by:)` for coordinate
+transforms needed by composition operations that move page items
+between packages.
+
+## Acceptance criteria
+
+- [ ] `Geometry.translate(point:, by:)` returns a new `[x, y]` pair
+      translated by the given offset.
+- [ ] Supports the IDML coordinate convention: origin at bottom-left
+      of the spread, y increasing upward.
+- [ ] Spec: translate a known point by a known offset, verify the
+      math matches SimpleIDML's reference implementation.
+
+## Files
+
+- `lib/idml/geometry.rb`
+- `spec/idml/geometry_spec.rb`
+
+## Design notes
+
+- The IDML coordinate system and how page-item coordinates map to
+  spread coordinates are documented in
+  `~/src/external/SimpleIDML/doc/IDML_insert_idml_coordinate_transformation.*`.
+- Start with `translate` (additive offset). Future operations
+  (`scale`, `rotate`) can be added as separate methods.
+
+## Dependencies
+
+- None (pure math).

data/TODO.complete/15-cli.md

@@ -0,0 +1,44 @@
+# TODO 15: CLI
+
+## Goal
+
+`exe/idml` binary exposing the gem's main operations as a
+command-line tool. Useful for ad-hoc IDML inspection and
+round-trip verification without writing Ruby.
+
+## Acceptance criteria
+
+- [ ] `idml parts path.idml` lists every entry name in the package.
+- [ ] `idml validate path.idml` runs Jing against each schematized
+      part and reports per-part status. Exit non-zero if any part
+      fails.
+- [ ] `idml round-trip path.idml -o output.idml` extracts every
+      part and writes a new IDML; verifies byte-equivalence.
+- [ ] `idml prefix path.idml PREFIX -o output.idml` prefixes every
+      Self attribute and writes a new IDML.
+- [ ] `idml version` prints the gem version.
+- [ ] `--help` and `-h` work for each command.
+- [ ] Spec: invoke each subcommand via `Idml::CLI` and verify
+      stdout/stderr/exit code.
+
+## Files
+
+- `exe/idml`
+- `lib/idml/cli.rb`
+- `lib/idml/cli/command.rb` (base class with common helpers)
+- `lib/idml/cli/{parts,validate,round_trip,prefix,version}.rb`
+- `lib/idml.rb` — autoload `CLI`.
+- `spec/idml/cli_spec.rb`
+
+## Design notes
+
+- Use `Thor` for the CLI framework (De facto Ruby standard). Add
+  `thor` as a runtime dependency.
+- Each command is a class — open/closed. New commands add a file,
+  not edit a switch statement.
+- The CLI is a thin wrapper around the gem's existing API; no
+  business logic lives in the CLI.
+
+## Dependencies
+
+- TODOs 02, 09, 10 (Package, Validation, Composition::Prefix).

data/TODO.complete/16-cross-version-tolerance.md

@@ -0,0 +1,40 @@
+# TODO 16: Cross-version tolerance
+
+## Goal
+
+Make the gem usable with IDML files from older InDesign versions
+without forcing strict DOMVersion matches. Document the policy
+clearly in code and README.
+
+## Acceptance criteria
+
+- [ ] Document the strict-validation-is-version-scoped rule in the
+      README and in `Idml::Validation::Validator` docs.
+- [ ] Add `Validator#loose_validate_part` that runs Jing with a
+      permissive flag (or strips the DOMVersion attribute before
+      validation) so older files can be checked against the
+      current schema for everything except version drift.
+- [ ] Add a `Package#dom_version` convenience that reads the
+      version from designmap.
+- [ ] Specs cover: a known-good current fixture validates strict;
+      the older `helloworld-1.idml` (2017, DOMVersion 13.x) passes
+      loose validation but fails strict.
+
+## Files
+
+- `lib/idml/validation/validator.rb` — add `loose_validate_part`.
+- `lib/idml/package.rb` — add `dom_version` accessor.
+- `spec/idml/validation/cross_version_spec.rb`
+- `README.adoc` — section on version compatibility.
+
+## Design notes
+
+- "Loose" means: tolerate DOMVersion mismatches; report every
+  other schema violation. Implementation: pre-process the XML to
+  blank out the DOMVersion attribute before passing to Jing.
+- The helloworld fixture from idmltools samples is the canonical
+  "older version" test case.
+
+## Dependencies
+
+- TODOs 02, 03, 09.

data/TODO.complete/17-yard-documentation.md

@@ -0,0 +1,38 @@
+# TODO 17: YARD documentation
+
+## Goal
+
+Document the public API with YARD tags so users get rich docs
+(`yard server`), and RubyGems.org shows API docs.
+
+## Acceptance criteria
+
+- [ ] Every public class (`Idml`, `Package`, `Document`,
+      `Parts::Designmap`, `Composition::Prefix`, `Validation::Validator`)
+      has YARD docstrings covering purpose, parameters, return type.
+- [ ] Every public method has `@param` and `@return` tags.
+- [ ] Add `yard` and `yard-rspec` (if useful) to the Gemfile
+      development group.
+- [ ] Add `.yardopts` configuring the build.
+- [ ] Add `rake yard` task to generate docs locally.
+- [ ] Rakefile `default` task unchanged (still spec + rubocop).
+- [ ] CI workflow runs `yard` to confirm docs build without
+      errors (does not gate the merge).
+
+## Files
+
+- All `lib/idml/*.rb` — add docstrings.
+- `Gemfile` — add `yard`.
+- `.yardopts`
+- `Rakefile` — add `yard` task.
+
+## Design notes
+
+- Don't gold-plate. Cover the public API; private internals get
+  short docstrings only where the why isn't obvious.
+- Use `@example` blocks for non-trivial usage (Document#find_by_self,
+  InsertIdml#call, etc.).
+
+## Dependencies
+
+- TODOs 11, 12 (so docs cover the accessors and Document API).

data/TODO.complete/18-remove-nokogiri.md

@@ -0,0 +1,38 @@
+# TODO 18: Remove Nokogiri dependency entirely
+
+## Goal
+
+Strip Nokogiri from the gem. Nokogiri is a heavy C-extension XML
+library; the gem should be fully model-driven through `lutaml-model`,
+falling back to REXML (stdlib) for ad-hoc XML manipulation the typed
+models don't yet cover.
+
+## Acceptance criteria
+
+- [ ] `lib/idml/document.rb` no longer requires or references Nokogiri.
+      Uses REXML (`rexml/document`) for ad-hoc XML queries.
+- [ ] `lib/idml/composition/insert_idml.rb` no longer requires or
+      references Nokogiri. `BackingStoryMerger` uses REXML.
+- [ ] `idml.gemspec` no longer declares `nokogiri` as a dependency.
+- [ ] `Gemfile` no longer includes `gem "nokogiri"`.
+- [ ] No file in `lib/` requires or references Nokogiri (enforced by
+      the anti-pattern spec — see TODO 21).
+- [ ] All existing specs continue to pass.
+
+## Files
+
+- `lib/idml/document.rb` — refactor.
+- `lib/idml/composition/insert_idml.rb` — refactor.
+- `idml.gemspec`, `Gemfile` — remove nokogiri.
+
+## Design notes
+
+- REXML is stdlib; no install friction. Slower than Nokogiri but
+  adequate for IDML files (typically < 1 MB per part).
+- The long-term goal is full type coverage so even REXML goes away —
+  every query routed through typed model methods. REXML is a stopgap
+  for parts of the model not yet typed.
+
+## Dependencies
+
+- None (reversible refactor).

data/TODO.complete/19-vendor-fixtures.md

@@ -0,0 +1,44 @@
+# TODO 19: Vendor IDML fixtures from reference repos
+
+## Goal
+
+Build a comprehensive `.idml` fixture corpus under `spec/fixtures/`
+by pulling every unique `.idml` file from the reference repos. The
+corpus anchors TODO 20's round-trip suite.
+
+## Acceptance criteria
+
+- [ ] `spec/fixtures/simple_idml/` contains every unique `.idml` from
+      `~/src/external/SimpleIDML/tests/regressiontests/IDML/`
+      (excluding `expected/` subdir).
+- [ ] `spec/fixtures/patrick_agostini/` contains the 6 shared fixtures
+      from `~/src/external/idml/tests/data/` (text, multipage, themes,
+      placeholders, bounded-text, shapes).
+- [ ] `spec/fixtures/joris_ros/` contains `example.idml` from
+      `~/src/external/IDMLlib/tests/assets/`.
+- [ ] `spec/fixtures/adobe_idmltools/` contains `helloworld-1.idml`
+      and `helloworld-2.idml` from the curated plugin_sdk_21 tree.
+- [ ] Existing `spec/fixtures/sample-with-image/` stays in place.
+- [ ] `spec/fixtures/ATTRIBUTION.md` documents the source repo and
+      license for each fixture directory.
+
+## Files
+
+- `spec/fixtures/simple_idml/*.idml` (~15 files)
+- `spec/fixtures/patrick_agostini/*.idml` (6 files)
+- `spec/fixtures/joris_ros/*.idml` (1 file)
+- `spec/fixtures/adobe_idmltools/*.idml` (2 files)
+- `spec/fixtures/ATTRIBUTION.md`
+
+## Design notes
+
+- Don't copy `expected/` from SimpleIDML — those are SimpleIDML's own
+  test outputs, not canonical inputs.
+- Don't add `.indd` files; we don't read `.indd`.
+- Some fixtures are older (InDesign CS5–CS6 era, DOMVersion ~7–8).
+  They won't validate against the InDesign 2026 schemas but should
+  still round-trip byte-equivalent via the Package layer.
+
+## Dependencies
+
+- None.

data/TODO.complete/20-round-trip-all-fixtures.md

@@ -0,0 +1,39 @@
+# TODO 20: Full round-trip suite across every fixture
+
+## Goal
+
+For every `.idml` file under `spec/fixtures/`, verify that opening,
+extracting every part, and writing a new package yields byte-equivalent
+parts (per entry, ignoring ZIP metadata like timestamps).
+
+## Acceptance criteria
+
+- [ ] `spec/idml/round_trip_all_fixtures_spec.rb` parameterized over
+      every `.idml` in `spec/fixtures/**/*.idml`.
+- [ ] For each fixture: open, extract parts, write to temp, reopen,
+      assert each entry's content is byte-equivalent to the original.
+- [ ] Skip entries that are inherently non-deterministic (none expected
+      for IDML — all parts are static XML or fixed mimetype).
+- [ ] Aggregate failures clearly: one RSpec example per fixture, named
+      with the relative path.
+- [ ] Document any fixture that fails round-trip in
+      `spec/fixtures/ROUND_TRIP_NOTES.md` with the specific reason.
+
+## Files
+
+- `spec/idml/round_trip_all_fixtures_spec.rb`
+- `spec/fixtures/ROUND_TRIP_NOTES.md` (only if any fixture fails)
+
+## Design notes
+
+- The round-trip test goes through `Package#each_part` + `Package.write`
+  — the raw XML passthrough. Typed models aren't involved; this test
+  validates the ZIP layer's byte fidelity.
+- For each fixture, the test creates a tempdir, writes the repackaged
+  ZIP there, reopens, and compares per-entry.
+- The existing `spec/idml/round_trip_spec.rb` (single fixture) can be
+  replaced by the parameterized version.
+
+## Dependencies
+
+- TODO 19 (fixtures vendored).

data/TODO.complete/21-anti-pattern-forbid-nokogiri.md

@@ -0,0 +1,31 @@
+# TODO 21: Anti-pattern spec forbids Nokogiri
+
+## Goal
+
+Encode the "no Nokogiri" rule in the anti-pattern spec so it can never
+accidentally come back. The check fires on any `require "nokogiri"` or
+`Nokogiri::` reference in `lib/`.
+
+## Acceptance criteria
+
+- [ ] `spec/anti_patterns_spec.rb` adds a new check per lib file: no
+      `nokogiri` in require statements, no `Nokogiri` constant
+      references.
+- [ ] Remove `nokogiri` from the existing external-require allowlist.
+- [ ] Spec documents WHY (model-driven; lutaml-model is the XML
+      authority; Nokogiri is a stopgap we're eliminating).
+
+## Files
+
+- `spec/anti_patterns_spec.rb`
+
+## Design notes
+
+- The check is simple: scan each lib file's source for
+  `require%s+"nokogiri"` and `Nokogiri::`. Fail if found.
+- This is a project-specific rule, distinct from the global "no
+  internal require" check. Document both.
+
+## Dependencies
+
+- TODO 18 (Nokogiri removed so the spec passes from the start).

data/TODO.complete/22-claude-md-no-nokogiri.md

@@ -0,0 +1,29 @@
+# TODO 22: Encode "No Nokogiri" rule in CLAUDE.md
+
+## Goal
+
+Make the project-level ban on Nokogiri explicit in `CLAUDE.md` so
+future Claude instances don't re-introduce it. Add it to the
+conventions section.
+
+## Acceptance criteria
+
+- [ ] `CLAUDE.md` "Conventions" section adds a "No Nokogiri" rule
+      with rationale.
+- [ ] The rule references the anti-pattern check (TODO 21) as the
+      automated enforcement.
+- [ ] The rule documents the alternative: use `lutaml-model` typed
+      methods where possible; use REXML for ad-hoc XML manipulation.
+
+## Files
+
+- `CLAUDE.md`
+
+## Design notes
+
+- Keep the rule short — one bullet with one sentence of rationale.
+- The full reasoning lives in `TODO.complete/18-remove-nokogiri.md`.
+
+## Dependencies
+
+- TODOs 18, 21 (so the rule is enforced when it's documented).