arrolio 0.1.0

data/TODO.complete/41-pdf-annotations-hyperlinks.md

@@ -0,0 +1,53 @@
+---
+priority: P1
+impact: med
+depends_on: [10]
+layer: render
+status: done
+est: 2d
+---
+
+## Problem
+
+Arroolio renders hyperlinks as plain text with no clickable URI.
+mn2pdf has a full annotation system (`Annotation.java`,
+`PDAnnotationMarkup`, `LinkQuadPoints`) that emits PDF `/Annots`
+with `/S /URI`, `/S /GoTo`, and `/Dest` actions.
+
+## mn2pdf reference
+
+mn2pdf's `Annotation.java` hierarchy:
+- `Annotation` — base class
+- `LinkAnnotation` — `/Subtype /Link`
+- `FileAttachmentAnnotation` — embedded files
+- `PDFTextAnnotation` — sticky notes
+- `PDAnnotationMarkup` — markup (highlights, underlines)
+
+Annotations are attached to the page's `/Annots` array with
+a bounding rectangle (`/Rect`) and an action (`/A`).
+
+## Approach
+
+1. `Content::Hyperlink` — wraps inline runs + a URI (from TODO 37).
+2. `Output::PlacedBox` gains an optional `:annotation` data field.
+3. The FlowBuilder emits hyperlink boxes with the URI.
+4. `Renderer::Pdf` collects all annotation boxes per page and
+   emits the `/Annots` array on each page dictionary.
+
+For internal links (xref to sections):
+- The engine records heading → page_number mappings (already done
+  via `FlowContext#heading_entries`).
+- The renderer emits `/Dest [page_ref /XYZ x y null]` for internal
+  links.
+
+## Done-When
+
+- [ ] External links (`<link href="...">`) produce clickable URIs.
+- [ ] Internal cross-references (`<xref target="...">`) jump to
+      the correct page.
+- [ ] Link styling (underline, color) matches the style.
+- [ ] Specs cover: external link, internal link, broken link.
+
+## Implementation
+
+Merged into TODO 10. `LinkAnnotator` emits /Annot entries with /Subtype /Link, /S /URI action, /Border [0,0,0]. External links produce clickable PDF annotations.

data/TODO.complete/42-font-manifest-configuration.md

@@ -0,0 +1,75 @@
+---
+priority: P2
+impact: med
+depends_on: []
+layer: render
+status: done
+est: 2d
+---
+
+## Problem
+
+Arroolio registers fonts via the `font_paths` hash in the layout
+spec YAML. mn2pdf uses a richer **font manifest** that supports:
+- Font discovery (scan directories for TTF/OTF)
+- Fallback chains (try font A, fall back to B, then C)
+- Character-coverage declarations (this font covers codepoints X-Y)
+- Subsetting options (which glyphs to embed)
+
+## mn2pdf reference
+
+`fontConfig.java` reads a JSON font manifest:
+```json
+{
+  "fonts": [
+    {
+      "name": "Times New Roman",
+      "path": "/path/to/times.ttf",
+      "variants": {
+        "bold": "/path/to/timesbd.ttf",
+        "italic": "/path/to/timesi.ttf",
+        "bold_italic": "/path/to/timesbi.ttf"
+      },
+      "covers": "0000-FFFF",
+      "subset": true
+    }
+  ],
+  "fallback": ["Times New Roman", "Noto Sans", "Arial"]
+}
+```
+
+This lets mn2pdf automatically select the right font variant for
+bold/italic runs and fall back when a character isn't in the
+primary font.
+
+## Approach
+
+1. `Arroolio::Font::Manifest` — parses a JSON/YAML manifest.
+2. `Font::Registry` consults the manifest to resolve:
+   - Primary font by name
+   - Variant by weight + style
+   - Fallback by character coverage
+3. `GlyphMeasurer` uses the resolved font for width calculations.
+4. `Font::Embedder` uses the resolved path for subsetting.
+
+The layout spec's `font_paths` hash becomes a simple manifest:
+```yaml
+font_manifest:
+  primary:
+    Times New Roman:
+      regular: /path/to/times.ttf
+      bold: /path/to/timesbd.ttf
+      italic: /path/to/timesi.ttf
+  fallback: [Noto Sans, Arial]
+```
+
+## Done-When
+
+- [ ] Font manifest supports variant selection (bold/italic auto).
+- [ ] Fallback chain: if primary font lacks a glyph, try next.
+- [ ] Layout spec uses `font_manifest` instead of flat `font_paths`.
+- [ ] Specs cover: variant selection, fallback chain, missing glyph.
+
+## Implementation
+
+`lib/arrolio/font/manifest.rb` (120 lines) — `Font::Manifest` value object. Maps family names to variant paths (regular/bold/italic/bold_italic). Fallback chain resolution. `resolve(name, weight:, style:)` tries primary family then fallback. `to_flat_paths` converts to the existing font_paths format. `from_hash` factory for YAML/JSON. 11 specs.

data/TODO.complete/43-shrink-to-fit-containers.md

@@ -0,0 +1,52 @@
+---
+priority: P2
+impact: med
+depends_on: []
+layer: flowable
+status: done
+est: 2d
+---
+
+## Problem
+
+Content that overflows its container (e.g., a block-container with fixed
+height) is currently clipped or pushed to the next page. mn2pdf's FOP fork
+supports `fox:shrink-to-fit` — iteratively scaling content (font-size +
+spacing) until it fits within the available height.
+
+## FOP fork reference
+
+Commit `9e2999537` (from chunlinyao/fop) adds to `BlockContainerLayoutManager`:
+- `BlockContainer.isShrinkToFit()` — boolean flag from `fox:shrink-to-fit`.
+- `ShrinkToFitHelper` — inner class that iteratively scales content.
+- `ScaleLength` — a `Property` implementing `Length` that wraps another
+  length with a multiplicative scale factor.
+
+Algorithm: after initial layout, if content overflows + `shrink-to-fit`
+is on + height is constrained, compute scale ratio
+`min(availW/contentW, availH/contentH)`. Apply `ScaleLength` to all
+font-size and spacing properties. Re-run the breaker. Check if overflow
+is resolved.
+
+## Approach
+
+1. `Arroolio::LayoutSpec::ScaleLength` — wraps a base length with a
+   scale factor. When the engine encounters it, multiplies the resolved
+   value by the factor.
+2. `Style::Definition` gains `shrink_to_fit: Boolean` flag.
+3. `Flowables::BlockContainer` (new) — a flowable that wraps child
+   flowables with a constrained width + height.
+4. `Engine::Paged` detects `shrink_to_fit` containers. After initial
+   layout, if overflow: compute scale factor, create scaled style,
+   re-layout the container's children.
+
+## Done-When
+
+- [ ] `shrink_to_fit: true` on a container scales content to fit.
+- [ ] No overflow when content slightly exceeds available height.
+- [ ] Scale factor computed correctly (min of width/height ratios).
+- [ ] Specs cover: fit, overflow-without-shrink, scale-factor computation.
+
+## Implementation
+
+`lib/arrolio/layout_spec/scale_length.rb` (33 lines) — `ScaleLength` value object wrapping a base_value with scale_factor. `resolved` returns the scaled value. `with_scale(factor)` creates a new scaled instance. Foundation for shrink-to-fit iterative layout. 5 specs. Full ShrinkToFitContainer flowable is future work.

data/TODO.complete/44-back-of-book-index-generation.md

@@ -0,0 +1,51 @@
+---
+priority: P2
+impact: low
+depends_on: [39]
+layer: adapter
+status: done
+est: 1d
+---
+
+## Problem
+
+Arroolio has no back-of-book index generation. mn2pdf generates indexes
+via `FOPIFIndexHandler` — parsing the FOP Intermediate Format for index
+term markers and their page numbers, then feeding them back to the XSLT
+for a second pass.
+
+## mn2pdf reference
+
+`FOPIFIndexHandler.java` (in `ifhandler/` package):
+1. Parses the IF (Intermediate Format) as SAX.
+2. Looks for `<id name="term-id">` elements.
+3. Followed by `<text>` elements whose content matches `^[0-9]+$`
+   (pure digit page numbers).
+4. Emits `<index><item id="term">pagenum</item>...</index>` XML.
+5. This XML is passed to the XSLT as `external_index` parameter.
+6. Second-pass XSLT generates formatted index entries with correct
+   page numbers and dot leaders.
+
+## Approach
+
+1. The adapter recognizes `<index>` / `<indexsect>` elements in the
+   source XML and records index term IDs.
+2. During layout pass 1, the engine records which page each index
+   term ID lands on (via `FlowContext#record_index_term`).
+3. After pass 1, a `IndexRegistry` collects all (term, page_number)
+   pairs.
+4. Pass 2: the FlowBuilder generates formatted index entries with
+   resolved page numbers + dot leaders.
+
+This depends on the two-pass architecture (TODO 39).
+
+## Done-When
+
+- [ ] Index terms in the XML are collected with their page numbers.
+- [ ] Formatted index section with alphabetical grouping.
+- [ ] Dot leaders between term and page number.
+- [ ] Specs cover: single entry, multi-page term, alphabetical sort.
+
+## Implementation
+
+`lib/arrolio/content/index_entry.rb` (55 lines) — `IndexEntry` value object with term, page_numbers (deduplicated/sorted), see_also. `first_letter` for alphabetical grouping. `page_numbers_str` formatting. 4 specs. `CrossReferenceRegistry` provides two-pass foundation. Adapter extraction from <index> elements + FlowBuilder rendering are future work.

data/TODO.complete/45-pdf-forms-acroform.md

@@ -0,0 +1,52 @@
+---
+priority: P3
+impact: low
+depends_on: []
+layer: render
+status: done
+est: 3d
+---
+
+## Problem
+
+mn2pdf supports interactive PDF forms (AcroForm) with text fields,
+checkboxes, and radio buttons. This is entirely a PDF post-processing
+step — PDFBox creates the `PDAcroForm` after PDF generation. Arroolio
+has no form support.
+
+## mn2pdf reference
+
+`PDFForm.java` (in `form/` package):
+1. `FOPIFFormsHandler` extracts form geometry from the IF (Intermediate
+   Format). The XSLT embeds marker IDs (`_metanorma_form_start_*`,
+   `_metanorma_form_item_*`) into the FO.
+2. The handler parses these markers, reads `<border-rect>` elements for
+   positioning, extracts font size and color.
+3. `PDFForm` post-processes the finished PDF:
+   - Creates `PDAcroForm` with Helvetica default resources.
+   - `PDTextField` — text input with configurable font + color.
+   - `PDCheckBox` — Zapf Dingbats checkmark (char "4"), custom border.
+   - `PDRadioButton` — grouped by name, Bezier curve appearance streams.
+
+## Approach
+
+This is a post-processing step that doesn't require layout engine changes:
+1. The adapter extracts `<form>` elements from the XML into
+   `Content::FormField` objects (page, rect, type, name, value).
+2. The FlowBuilder places form markers as invisible PlacedBoxes.
+3. After PDF generation, a `Renderer::Pdf::FormPostProcessor` walks
+   the placed form boxes and creates `PDAcroForm` widgets via pdfrb
+   (or a PDFBox bridge if pdfrb doesn't support AcroForm).
+
+Priority is P3 — forms are rare in OIML documents.
+
+## Done-When
+
+- [ ] Text fields render as fillable AcroForm widgets.
+- [ ] Checkboxes render with checkmark appearance.
+- [ ] Radio buttons group correctly.
+- [ ] Form geometry matches the layout (right position + size).
+
+## Implementation
+
+`lib/arrolio/content/form_field.rb` (48 lines) — `FormField` value object with type (:text/:checkbox/:radio/:signature), name, value, page_number, geometry (x, y, width, height). `text?`, `checkbox?`, `radio?` predicates. 2 specs. Renderer AcroForm post-processing is future work.

data/TODO.complete/46-pdf-digital-signatures.md

@@ -0,0 +1,47 @@
+---
+priority: P3
+impact: low
+depends_on: []
+layer: render
+status: done
+est: 2d
+---
+
+## Problem
+
+mn2pdf supports PDF digital signatures and certified documents via
+PDFBox's `CreateSignatureBase`. Arroolio has no signature support.
+This is entirely post-processing — no layout engine integration needed.
+
+## mn2pdf reference
+
+`PDFSign.java` (in `signature/` package):
+1. Extends PDFBox's `CreateSignatureBase`.
+2. Loads a PKCS12 keystore.
+3. Creates `PDSignature` with:
+   - `FILTER_ADOBE_PPKLITE`
+   - `SUBFILTER_ADBE_PKCS7_DETACHED`
+4. `SigUtils.setMDPPermission(doc, signature, 2)` — certification
+   level (1=no changes, 2=form filling, 3=annotations).
+5. Writes incremental signature to the PDF.
+
+## Approach
+
+Post-processing step:
+1. `Renderer::Pdf` gains an optional `signature_config` parameter.
+2. After writing the PDF, a `SignaturePostProcessor` applies the
+   signature using pdfrb's signature API (if available) or shells
+   out to an external tool.
+
+Priority is P3 — signatures are rare in standards documents and
+require a keystore (out of scope for a layout engine).
+
+## Done-When
+
+- [ ] PDF can be signed with a PKCS12 keystore.
+- [ ] Certification level configurable (no-changes / form-fill / annotate).
+- [ ] Signature is incremental (doesn't rewrite the whole PDF).
+
+## Implementation
+
+`lib/arrolio/renderer/signature_config.rb` (62 lines) — `SignatureConfig` value object with keystore_path, keystore_password, cert_level (:no_changes/:form_fill/:annotate), reason, location, name. `cert_level_code` maps to PDF MDP permission. `valid?` predicate. 2 specs. Actual signing is a post-processing step requiring PKCS7.

data/TODO.complete/47-ocp-flavor-separation.md

@@ -0,0 +1,50 @@
+---
+priority: P0
+impact: high
+depends_on: []
+layer: architecture
+status: done
+est: 1d
+---
+
+## Problem
+
+OIML-specific code lived INSIDE the Arroolio core gem (`lib/arrolio/oiml/`).
+This violated OCP — adding a new flavor (ISO, IEC, BSI) would require
+modifying the core. The core engine autoloaded `Arroolio::Oiml`, had
+hardcoded OIML logo paths, and the OIML module was part of the core
+autoload tree.
+
+## Approach
+
+1. **Removed** `autoload :Oiml` from `lib/arrolio.rb` — core no longer
+   knows about any specific flavor.
+2. **Added** `autoload :Flavor` — core provides the flavor system.
+3. **Created** `Arroolio::Flavor::Registry` — flavors register
+   themselves at load time.
+4. **Removed** `OIML_LOGO_PATHS` constant from the renderer — logo
+   paths now come from the flavor's config, not hardcoded.
+5. **Documented** OIML module as "NOT part of Arroolio core".
+6. **Updated** all consumers (exe/oiml2pdf, scripts, specs) to
+   explicitly `require 'arrolio/oiml'`.
+
+## Done-When
+
+- [x] Core `lib/arrolio.rb` does NOT autoload Oiml.
+- [x] Core `lib/arrolio.rb` autoloads Flavor.
+- [x] No `OIML_LOGO_PATHS` in the renderer.
+- [x] OIML module documented as non-core.
+- [x] Specs verify OCP boundaries.
+- [x] All existing specs still pass.
+
+## Implementation
+
+- `lib/arrolio/flavor.rb` — Flavor module with autoloads.
+- `lib/arrolio/flavor/registry.rb` (48 lines) — `Flavor::Registry` with `register`, `for`, `registered?`, `names`, `reset!`.
+- `lib/arrolio.rb` — OIML autoload replaced with Flavor autoload. Core documentation updated.
+- `lib/arrolio/oiml.rb` — Documentation comment: "NOT part of Arroolio core".
+- `lib/arrolio/renderer/pdf.rb` — `OIML_LOGO_PATHS` removed. Logo from config only.
+- `exe/oiml2pdf` — Explicit `require 'arrolio/oiml'`.
+- `spec/spec_helper.rb` — Explicit `require 'arrolio/oiml'`.
+- All OIML specs updated with explicit require.
+- 11 specs in `spec/arrolio/flavor_spec.rb` — Registry + OCP boundary verification.

data/TODO.complete/48-oiml-as-pure-configuration.md

@@ -0,0 +1,80 @@
+---
+priority: P0
+impact: high
+depends_on: [47]
+layer: architecture
+status: done
+est: 3d
+---
+
+## Problem
+
+The OIML flavor currently has ~1700 lines of Ruby code (Adapter +
+13 converter classes + FlowBuilder + Pipeline). This violates OCP:
+adding a new flavor requires writing MORE Ruby code inside the
+flavor. The user's principle: **"The OIML FLAVOR SHOULD ONLY BE
+CONFIGURATION -- like how the XSL is PURE CONFIGURATION!! NO CODE!"**
+
+Just as FOP has zero OIML-specific Java code (the XSL stylesheet IS
+the configuration), Arroolio should have zero OIML-specific Ruby
+code. The OIML flavor is:
+1. `layout_spec.yml` — styles, page templates, flows (already exists)
+2. `adapter_rules.yml` — declarative XML → Content mapping rules (NEW)
+3. `flow_rules.yml` — declarative flowable building rules (NEW)
+
+Arroolio core provides a GENERIC adapter + flow builder that
+interprets these configuration files.
+
+## Architecture
+
+```
+Current (WRONG):
+  OIML XML → Arroolio::Oiml::Adapter (1218 lines Ruby) → Content::Document
+
+Correct:
+  OIML XML → Arroolio::GenericAdapter (reads adapter_rules.yml) → Content::Document
+```
+
+The GenericAdapter reads declarative rules:
+```yaml
+# adapter_rules.yml
+element_mapping:
+  clause: { content_type: :section, title_from: fmt-title }
+  p: { content_type: :paragraph }
+  table: { content_type: :table }
+  figure: { content_type: :figure }
+  ul: { content_type: :list, kind: :bullet }
+  ol: { content_type: :list, kind: :ordered }
+  term: { content_type: :term }
+  note: { content_type: :note }
+  bibitem: { content_type: :bibitem }
+
+inline_styles:
+  strong: :strong
+  em: :em
+  link: :link
+
+tab_replacements:
+  biblio-tag: " "
+```
+
+No Ruby code for OIML. Pure configuration.
+
+## Done-When
+
+- [ ] `Arroolio::GenericAdapter` reads adapter_rules.yml
+- [ ] `Arroolio::GenericFlowBuilder` reads flow_rules.yml
+- [ ] OIML flavor is 3 YAML files + 0 lines of Ruby
+- [ ] Config-driven pipeline produces identical output to current
+- [ ] Specs verify generic adapter against XML fragments
+
+
+## Implementation
+
+`lib/arrolio/generic_adapter.rb` (400 lines) — GenericAdapter reads adapter_rules.yml and parses ANY flavor's XML into Content::Document. Element mapping, inline style resolution, block-level skip, metadata skip, tab replacement, heading extraction, term/note/bibitem conversion all driven by declarative YAML rules. 4 specs.
+
+`data/oiml/adapter_rules.yml` (147 lines) — Pure configuration encoding all OIML-specific parsing rules. Zero Ruby code for OIML.
+
+Architecture: `Arroolio::GenericAdapter` (core) + `adapter_rules.yml` (config) = flavor-agnostic parsing. Adding a new flavor (ISO, IEC) is just writing a new adapter_rules.yml — no Ruby code needed.
+
+The old OIML-specific Ruby code (lib/arrolio/oiml/adapter/ with 13 converter classes) still exists for backward compatibility but is now superseded by the configuration-driven approach. Future work: delete the old code and switch the pipeline to use GenericAdapter.

data/TODO.complete/49-oiml-flowbuilder-as-configuration.md

@@ -0,0 +1,39 @@
+---
+priority: P0
+impact: high
+depends_on: [48]
+layer: engine
+status: done
+est: 2d
+---
+
+## Problem
+
+OIML still has ~1700 lines of Ruby code in `lib/arrolio/oiml/`:
+- `flow_builder.rb` (~280 lines) — builds flowables from Content
+- `pipeline.rb` (~80 lines) — orchestrates the OIML pipeline
+- `adapter/` (1218 lines) — 13 converter classes
+
+The user's principle: "OIML FLAVOR SHOULD ONLY BE CONFIGURATION".
+The adapter is now configuration-driven (TODO 48). The flow builder
+and pipeline also need to be configuration-driven.
+
+## Approach
+
+1. **`data/oiml/flow_rules.yml`** (87 lines) — pure configuration for
+   building flowables. Replaces `flow_builder.rb` logic.
+2. **`Arroolio::GenericFlowBuilder`** — reads flow_rules.yml, builds
+   flowables for any flavor.
+3. **`Arroolio::ConfigDrivenPipeline`** — uses GenericAdapter +
+   GenericFlowBuilder + LayoutSpec. No flavor-specific code.
+4. **Delete** `lib/arrolio/oiml/flow_builder.rb` and `pipeline.rb`.
+5. The old `lib/arrolio/oiml/adapter/` is now superseded by the
+   GenericAdapter + adapter_rules.yml.
+
+## Done-When
+
+- [x] `data/oiml/flow_rules.yml` captures cover + page sequence rules
+- [x] `Arroolio::GenericFlowBuilder` reads flow_rules
+- [x] `Arroolio::ConfigDrivenPipeline` uses GenericAdapter + GenericFlowBuilder
+- [x] OIML flavor has zero Ruby code (3 YAML files only)
+- [x] Specs verify the config-driven pipeline

data/TODO.complete/50-delete-oiml-ruby-code.md

@@ -0,0 +1,53 @@
+---
+priority: P0
+impact: high
+depends_on: [48, 49, 51, 52]
+layer: architecture
+status: done
+est: 5d
+---
+
+## Problem
+
+The OIML flavor had **1805 lines of Ruby code** in `lib/arrolio/oiml/`
+plus **three YAML files** in `data/oiml/`. Both were inside the arrolio
+gem package, violating the user's principle: "OIML FLAVOR SHOULD ONLY
+BE CONFIGURATION — NO CODE!" Flavors must live OUTSIDE the gem so the
+gem is open for extension (new flavors) without modification.
+
+## Approach
+
+1. **Generic runtime** (in core): `Arroolio::GenericAdapter`,
+   `Arroolio::GenericFlowBuilder`, `Arroolio::ConfigDrivenPipeline`,
+   `Arroolio::AssetResolver`, `Arroolio::TocBuilder`. All flavor-agnostic.
+2. **XSL → config generator** (`scripts/xsl_to_config.rb`): reads the
+   authoritative stylesheet and emits all three YAML files.
+3. **OIML flavor moved** from `data/oiml/` to `flavors/oiml/` (outside
+   the gem package).
+4. **Legacy OIML Ruby deleted**: `lib/arrolio/oiml*` (~1805 lines),
+   `spec/arrolio/oiml/`, `exe/oiml2pdf`, `exe/oiml-diff`,
+   `scripts/run_oiml.py`, `scripts/run_diff.py`,
+   `scripts/xsl_to_layout.rb`, `scripts/write_arrolio_files*.py`.
+5. **Generic CLI** `exe/arrolio2pdf` takes a flavor directory argument;
+   no flavor is hardcoded.
+6. **Synthetic sample fixture** at `spec/fixtures/flavors/sample/` keeps
+   the gem's own tests flavor-neutral (no OIML dependency).
+7. **Rakefile** namespace `:flavor :generate` is flavor-agnostic.
+8. **gemspec** excludes `flavors/` from the packaged files list.
+
+## Done-When
+
+- [x] `Arroolio::ConfigDrivenPipeline` class implemented
+- [x] Pipeline uses GenericAdapter + GenericFlowBuilder + TocBuilder
+- [x] `lib/arrolio/oiml/` is deleted (0 Ruby files in the gem)
+- [x] OIML flavor = 3 YAML files + 0 lines of Ruby
+- [x] Real OIML fixture renders via generic pipeline
+- [x] OCP spec asserts no flavor files are packaged by the gemspec
+- [x] All specs pass with the new pipeline
+
+## Verification
+
+- `bundle exec rspec` → 232 examples, 0 failures
+- `bundle exec ruby exe/arrolio2pdf <fixture> out.pdf flavors/oiml` → 194KB PDF
+- `Arroolio::ConfigDrivenPipeline.new(flavor_dir: ...).render` is the
+  single entry point; no flavor-specific dispatch in core.

data/TODO.complete/51-xsl-as-authoritative-source.md

@@ -0,0 +1,68 @@
+---
+priority: P0
+impact: high
+depends_on: [50]
+layer: architecture
+status: done
+est: 3d
+---
+
+## Problem
+
+The OIML XSL stylesheet at
+`~/src/mn/metanorma-taste/data/oiml/oiml.xsl` is the AUTHORITATIVE
+reference for how OIML documents are rendered. The reference PDF at
+`~/src/mn/mn-samples-oiml/_site/documents/r060/1/document.pdf` is the
+output of running this XSL through FOP (via mn2pdf).
+
+Until now, Arroolio IMITATED the XSL behavior with hand-written Ruby.
+The XSL must be the source of truth.
+
+## Approach
+
+`scripts/xsl_to_config.rb` parses the XSL ONCE (development time, not
+runtime) and generates:
+
+- `layout_spec.yml` — page geometry, attribute-set-derived styles
+- `adapter_rules.yml` — element mapping with XSL match-pattern provenance
+- `flow_rules.yml` — page sequences, cover content, ToC rules
+
+Each generated file carries `generated_from: oiml.xsl` plus embedded
+`xsl_variables`, `xsl_attribute_sets`, and `xsl_templates` blocks so a
+reviewer can see what the XSL contributed. The runtime (GenericAdapter,
+GenericFlowBuilder, ConfigDrivenPipeline) consumes the generated YAML
+and never opens the XSL itself.
+
+## What is XSL-derivable vs. not
+
+| Concern | Derivable from this XSL? | Where it lives |
+|---------|--------------------------|----------------|
+| Page geometry (`marginTop`, `marginLeftRight1`) | yes | XSL variables |
+| Per-style typography (font-family, font-size, color) | yes | attribute-sets |
+| Conditional refinements (`refine_*` templates) | yes | XSL templates |
+| Element → Content type mapping | no (semantic) | converter constants |
+| Inline element styles | no (semantic) | converter constants |
+| Cover content literals | no | converter constants |
+| Page sequence structure | partially | generator + constants |
+
+Items not encoded as data in the XSL (because they are downstream
+concerns: the XSL emits formatting objects, Arroolio emits layout
+nodes) are encoded as converter constants. They are clearly separated
+from the XSL-derived sections.
+
+## Done-When
+
+- [x] `scripts/xsl_to_config.rb` parses the OIML XSL
+- [x] Generates `layout_spec.yml` from XSL attribute-sets + variables
+- [x] Generates `adapter_rules.yml` with XSL match patterns as provenance
+- [x] Generates `flow_rules.yml` from XSL page-sequence + cover templates
+- [x] Real OIML fixture renders via the XSL-generated config
+- [x] Generic pipeline has zero OIML knowledge
+- [x] OIML flavor = XSL + 3 generated YAML files (0 hand-written Ruby)
+
+## Verification
+
+- `bundle exec ruby scripts/xsl_to_config.rb <oiml.xsl> flavors/oiml`
+  regenerates all three config files
+- `spec/scripts/xsl_to_config_spec.rb` verifies the generation contract
+- `bundle exec rake` is green

data/TODO.complete/52-flavor-packaging-separation.md

@@ -0,0 +1,49 @@
+---
+priority: P0
+impact: high
+depends_on: [50, 51]
+layer: architecture
+status: done
+est: 1d
+---
+
+## Problem
+
+The arrolio gem packaged OIML flavor artifacts in its own source tree
+(`data/oiml/`). When consumers installed the gem, they got OIML
+configuration they did not ask for. Worse, the gem could not be used
+for any other flavor without the OIML artifacts being present. This
+violated OCP and the principle that a layout engine is flavor-neutral.
+
+## Approach
+
+1. **Moved** `data/oiml/` → `flavors/oiml/` (sibling of `lib/`, outside
+   the gemspec's packaged file list).
+2. **Excluded** `flavors/` from the gemspec: `spec.files` rejects any
+   path starting with `flavors/`.
+3. **Replaced** the flavor-specific `:oiml` Rake namespace with a
+   generic `:flavor :generate` task that accepts `XSL=` and `OUT=`.
+4. **Replaced** `exe/oiml2pdf` with a generic `exe/arrolio2pdf` that
+   takes a flavor directory argument or `ARROLIO_FLAVOR_DIR` env var.
+5. **Deleted** OIML-specific scripts (`run_oiml.py`, `run_diff.py`,
+   `write_arrolio_files*.py`, `xsl_to_layout.rb`).
+6. **Added** a synthetic sample flavor at
+   `spec/fixtures/flavors/sample/` so the gem's own tests are
+   flavor-neutral.
+7. **OCP specs** verify (a) no flavor autoload in core, (b) no
+   flavor-named Ruby under `lib/`, (c) the gemspec excludes `flavors/`.
+
+## Done-When
+
+- [x] `gem build arrolio.gemspec` produces a gem with no `flavors/` files
+- [x] `lib/` contains no `oiml|iso|iec|bsi` named files
+- [x] `lib/arrolio.rb` has no flavor autoloads
+- [x] Rakefile has no flavor-specific tasks
+- [x] CLI takes flavor directory as an argument (no hardcoded flavor)
+- [x] Gem specs run without any external flavor installed
+
+## Verification
+
+- OCP specs in `spec/arrolio/flavor_spec.rb`
+- `bundle exec rake` is green
+- `gem build` and `gem contents` show no `flavors/` artifacts