arrolio 0.1.0

data/TODO.implementation/55-pdf-comparator.md

@@ -0,0 +1,98 @@
+---
+priority: P0
+phase: 17
+depends_on: [54]
+layer: harness
+est: 5d
+status: pending
+---
+
+## Problem
+
+Modeled on `Canon::Comparison`, Arrolio needs a semantic PDF
+comparator: take two PDFs (ours vs FOP reference), produce a
+`DiffReport` of `DiffNode`s classified by **dimension** (text,
+font, position, colour, image, vector, structure) and by
+**severity** (normative vs informative formatting drift).
+
+This is the **primary** diff mode. Pixel diff (TODO 59) is one
+optional input; RSpec matchers (TODO 58) and formatters (TODO 56)
+consume the report.
+
+## Approach
+
+Inspired by `~/src/lutaml/canon/lib/canon/comparison/` — same shape,
+different domain.
+
+### Files under `lib/arrolio/harness/comparator/`
+
+- `base_comparator.rb` — abstract: takes two `Pdfrb::Document`
+  instances, produces `DiffReport`.
+- `pdf_comparator.rb` — concrete comparator for PDF vs PDF.
+- `dimension.rb` — base class for a diff dimension. Each subclass
+  compares one aspect of two corresponding elements.
+- `dimension_set.rb` — registry of active dimensions per profile.
+- `dimensions/` — one file per dimension:
+  - `text_content.rb` — string-equality on extracted text per
+    PlacedBox.
+  - `text_order.rb` — reading order across the page.
+  - `font.rb` — font family, size, weight, colour.
+  - `position.rb` — x/y/width/height within a page (with tolerance).
+  - `colour.rb` — fill/stroke colour match.
+  - `image_content.rb` — perceptual hash (pHash) for embedded images.
+  - `vector_path.rb` — path-data comparison for line/curve shapes.
+  - `structure.rb` — page count, region count, element nesting.
+  - `metadata.rb` — `/Info`, `/Metadata` XMP.
+- `classifier.rb` — marks each `DiffNode` as `:normative` (changes
+  reader-visible meaning) or `:informative` (formatting drift within
+  tolerance). Used by RSpec matchers to decide pass/fail.
+- `match_options.rb` — per-dimension tolerances (e.g. position
+  tolerance 0.5pt; phash hamming distance ≤ 5).
+- `profile.rb` — presets:
+  - `:strict` — zero tolerance, all dimensions active.
+  - `:content_only` — text + structure only.
+  - `:visual_equiv` — text + image + colour, ignore exact position.
+  - `:oiml_regression` — OIML-tuned: position tolerance 1pt,
+    font-metric exact, ignore running-header date.
+
+### Algorithm
+
+```
+1. Parse both PDFs via Pdfrb.
+2. Walk pages pairwise (different page counts → structural diff).
+3. Per page, walk regions pairwise.
+4. Per region, walk PlacedBoxes pairwise (matching by reading order).
+5. For each pair, run every active dimension; collect DiffNodes.
+6. Classifier labels each DiffNode.
+7. Return DiffReport.
+```
+
+Pairing across pages/regions uses reading-order + position heuristics
+(canonical: top-to-bottom, left-to-right). When pairing is ambiguous,
+emit a `:structure` diff with both candidates.
+
+### DiffReport
+
+```ruby
+class Arrolio::Harness::DiffReport
+  attr_reader :differences, :profile, :stats
+
+  def normative_diffs; differences.select(&:normative?); end
+  def informative_diffs; differences.reject(&:normative?); end
+  def equivalent?(profile); normative_diffs.empty?; end
+  def similarity -> Float in [0, 1]
+end
+```
+
+## Done-When
+
+- [ ] Two identical PDFs produce `equivalent?(:strict) == true`.
+- [ ] PDFs differing in one paragraph's text produce one
+      `:text_content` DiffNode, classified normative.
+- [ ] PDFs differing in font size by 0.1pt produce one `:font`
+      DiffNode, classified informative (within default tolerance).
+- [ ] PDFs with different page counts produce a `:structure` diff.
+- [ ] Different embedded images produce `:image_content` diff with
+      phash distance.
+- [ ] Profile selection correctly activates/deactivates dimensions.
+- [ ] Specs cover each dimension + classifier + at least 2 profiles.

data/TODO.implementation/56-diff-formatters.md

@@ -0,0 +1,95 @@
+---
+priority: P0
+phase: 17
+depends_on: [55]
+layer: harness
+est: 3d
+status: pending
+---
+
+## Problem
+
+`DiffReport` is data; users need it rendered. Different audiences
+need different views:
+
+- **CI / regression test**: machine-readable JSON + pass/fail summary.
+- **Developer local**: pretty terminal output with colour and context.
+- **Designer review**: HTML report with side-by-side pages and
+  highlighted diff regions (paired with pixel-diff images from
+  TODO 59 when available).
+- **Audit log**: by-element dump with canonical paths.
+
+Modeled on `Canon::DiffFormatter::*` (by_line, by_object,
+pretty_diff_formatter, diff_detail_formatter).
+
+## Approach
+
+Files under `lib/arrolio/harness/formatters/`:
+
+- `base_formatter.rb` — abstract: takes `DiffReport`, returns String
+  (or writes to IO).
+
+- `summary_formatter.rb` — one-line pass/fail + similarity %.
+  Example: `✓ equivalent (97.3% similarity, 4 informative diffs)`.
+  Used as the first line of every other format.
+
+- `pretty_formatter.rb` — coloured terminal output. Groups diffs by
+  severity (normative first), then by page. Each diff shows:
+  - Dimension icon (📝 text, 🔤 font, 📍 position, 🎨 colour, 🖼 image).
+  - Canonical path (TODO 57).
+  - Before/after snippet (truncated to 60 chars).
+  - Reason phrase.
+
+- `by_page_formatter.rb` — per-page section; lists every diff on
+  that page. Good for "what's wrong with page 7?".
+
+- `by_element_formatter.rb` — per-element-namespace section. Lists
+  every diff affecting e.g. all tables, all headings.
+
+- `json_formatter.rb` — machine-readable JSON for CI integration.
+  Schema:
+  ```json
+  {
+    "equivalent": false,
+    "similarity": 0.873,
+    "profile": "oiml_regression",
+    "normative_diffs": [...],
+    "informative_diffs": [...]
+  }
+  ```
+
+- `html_formatter.rb` — standalone HTML report. Embeds:
+  - Page thumbnails (left: reference, right: ours) with diff regions
+    boxed.
+  - Per-diff detail panel.
+  - Filter controls (hide informative, hide by dimension).
+  - Uses pixel-diff images (TODO 59) when available.
+
+- `junit_formatter.rb` — JUnit XML for CI systems that consume it
+  (Jenkins, GitLab CI).
+
+- `legend.rb` — explains icons, colours, dimension names. Shared
+  across formatters.
+
+- `theme.rb` — ANSI colour palette + HTML CSS variables.
+
+## Approach for diffs within a diff
+
+Use `Diff::LCS.sdiff` on the relevant extracted text (per page or
+per element) to produce line-level hunks. Wrap each hunk as a
+`DiffBlock` (modeled on `Canon::Diff::DiffBlock`). The formatter
+renders DiffBlocks with `+`/`-`/` ` prefixes and optional colour.
+
+## Done-When
+
+- [ ] `SummaryFormatter.(report)` returns a one-line pass/fail.
+- [ ] `PrettyFormatter.(report)` produces coloured terminal output
+      that fits in 80 columns.
+- [ ] `JsonFormatter.(report)` produces valid JSON parseable by
+      `JSON.parse`.
+- [ ] `HtmlFormatter.(report)` produces a valid HTML file openable
+      in a browser.
+- [ ] `JUnitFormatter.(report)` produces valid JUnit XML.
+- [ ] Each formatter has at least one fixture-based spec.
+- [ ] A CLI flag (`--format pretty|json|html|junit|summary`) selects
+      the formatter.

data/TODO.implementation/57-path-locator-and-enrichment.md

@@ -0,0 +1,74 @@
+---
+priority: P1
+phase: 17
+depends_on: [55]
+layer: harness
+est: 2d
+status: pending
+---
+
+## Problem
+
+Every `DiffNode` should carry a **canonical path** so users can
+pinpoint exactly where the difference is. Modeled on canon's
+`PathBuilder`, `SourceLocator`, `DiffNodeEnricher`, `DiffCharRange`,
+`DiffLine`, `DiffContext`.
+
+A canonical path looks like:
+```
+page[2].region[:body].flowable[3].line[1].run[0].text_content
+```
+
+Plus enrichment: each DiffNode should carry `serialized_before` /
+`serialized_after` snippets, `line_range_before` / `line_range_after`
+(line ranges in the source PDFs' content streams), and `char_ranges`
+(character-level diff within a changed text run).
+
+## Approach
+
+Files under `lib/arrolio/harness/`:
+
+- `path_builder.rb` — constructs canonical paths. Walks the DiffNode's
+  source location chain (page → region → flowable → line → run →
+  property) and builds the dotted path. Each segment includes an
+  ordinal index for stable ordering.
+
+- `source_locator.rb` — given a `Pdfrb::Model::Object` reference,
+  returns its source location: `(page_number, oid, gen,
+  content_stream_offset)`.
+
+- `diff_node_enricher.rb` — post-processing pass over a `DiffNode[]`:
+  1. Compute canonical path via `PathBuilder`.
+  2. Serialize before/after content (text run, font dict, image
+     stream).
+  3. Compute line ranges in the source PDFs.
+  4. For text differences, run `Diff::LCS` on character level →
+     `DiffCharRange[]`.
+
+- `diff_char_range.rb` — value object: `start_before`, `end_before`,
+  `start_after`, `end_after`, `kind` (`:insert`, `:delete`,
+  `:replace`). Used by PrettyFormatter to highlight just the changed
+  characters within a run.
+
+- `diff_line.rb`, `diff_block.rb`, `diff_context.rb` — line-level
+  diff artifacts (same as canon's). Used by line-diff formatters.
+
+- `diff_classifier.rb` — refines the basic normative/informative
+  classification from TODO 55 with heuristics:
+  - Position drift under 1pt → informative.
+  - Font size drift under 0.1pt → informative.
+  - Colour drift under ΔE 2.0 (perceptual) → informative.
+  - Text content change of any kind → normative.
+  - Image phash distance ≤ 5 → informative.
+
+## Done-When
+
+- [ ] Every DiffNode has a non-nil `path` after enrichment.
+- [ ] Paths are stable across runs (same input → same paths).
+- [ ] `serialized_before` / `serialized_after` are non-nil for text
+      diffs; truncation is consistent (60 chars + ellipsis).
+- [ ] Character ranges highlight exactly the changed characters in a
+      text run.
+- [ ] Classifier correctly labels a 0.05pt font size drift as
+      informative.
+- [ ] Specs cover path building, enrichment, classifier thresholds.

data/TODO.implementation/58-rspec-matchers-and-harness-api.md

@@ -0,0 +1,124 @@
+---
+priority: P0
+phase: 17
+depends_on: [55, 56, 57]
+layer: harness
+est: 2d
+status: pending
+---
+
+## Problem
+
+For tests and CI, users need a fluent RSpec API. Two matchers cover
+the common cases:
+
+```ruby
+expect(our_pdf_bytes).to match_pdf(ref_path)              # strict
+expect(our_pdf_bytes).to be_equivalent_to_pdf(ref_path)   # ignores informative
+```
+
+Plus a programmatic `Arrolio::Harness.diff` for non-RSpec use.
+
+## Approach
+
+### RSpec matchers
+
+File: `lib/arrolio/harness/rspec.rb` (auto-registered into RSpec
+when required from `spec_helper.rb`).
+
+```ruby
+RSpec::Matchers.define :match_pdf do |reference_path|
+  match do |actual_bytes|
+    report = Arrolio::Harness.diff(
+      ours: actual_bytes,
+      reference: File.binread(reference_path),
+      profile: @profile || :strict
+    )
+    report.equivalent?(profile: @profile || :strict).tap do
+      @failure_report = report
+    end
+  end
+
+  chain :with_profile do |profile|
+    @profile = profile
+  end
+
+  failure_message do
+    Arrolio::Harness::Formatters::PrettyFormatter.(@failure_report)
+  end
+end
+
+RSpec::Matchers.define :be_equivalent_to_pdf do |reference_path|
+  # Same as match_pdf but profile: :content_only by default —
+  # ignores font-size drift, position drift under 1pt, etc.
+end
+```
+
+### Programmatic API
+
+File: `lib/arrolio/harness.rb`.
+
+```ruby
+module Arrolio::Harness
+  module_function
+
+  def diff(ours:, reference:, profile: :strict)
+    ours_doc    = Pdfrb::Document.new(io: StringIO.new(ours))
+    ref_doc     = Pdfrb::Document.new(io: StringIO.new(reference))
+    comparator  = Comparator::PdfComparator.new(profile:)
+    report      = comparator.compare(ours_doc, ref_doc)
+    DiffNodeEnricher.enrich(report)
+    report
+  end
+
+  def equivalent?(ours:, reference:, profile: :strict)
+    diff(ours:, reference:, profile:).equivalent?(profile:)
+  end
+
+  def format(report, format: :pretty)
+    Formatters.from_name(format).(report)
+  end
+end
+```
+
+### CLI integration
+
+Extend `exe/arrolio-oiml` (TODO 54):
+
+```sh
+# Diff our rendering of OIML XML against FOP's:
+arrolio-oiml diff document.presentation.xml \
+              --reference=document.fop.pdf \
+              --profile=oiml_regression \
+              --format=pretty|json|html|junit
+
+# Diff two pre-rendered PDFs:
+arrolio-harness diff ours.pdf ref.pdf --profile=strict
+```
+
+### Spec wiring
+
+In `spec/spec_helper.rb`:
+```ruby
+require "arrolio/harness/rspec"
+```
+
+Then `spec/arrolio/oiml/e2e_spec.rb` becomes:
+```ruby
+it "#{base} matches FOP reference" do
+  out = StringIO.new
+  Arrolio::Oiml::Pipeline.(xml, io: out)
+  expect(out.string).to be_equivalent_to_pdf(ref_pdf)
+    .with_profile(:oiml_regression)
+end
+```
+
+## Done-When
+
+- [ ] `require "arrolio/harness/rspec"` registers both matchers.
+- [ ] `match_pdf` fails with a useful pretty-formatted message.
+- [ ] `be_equivalent_to_pdf` ignores informative diffs by default.
+- [ ] `Arrolio::Harness.diff(...)` returns a `DiffReport`.
+- [ ] `Arrolio::Harness.equivalent?(...)` returns a bool.
+- [ ] CLI `arrolio-oiml diff ...` exits 0 on equivalent, 1 on diff.
+- [ ] CI-friendly: JSON formatter output stable across runs.

data/TODO.implementation/59-pixel-diff-mode.md

@@ -0,0 +1,93 @@
+---
+priority: P1
+phase: 17
+depends_on: [55, 57]
+layer: harness
+est: 2d
+status: pending
+---
+
+## Problem
+
+The semantic comparator (TODO 55) catches missing words and
+structural changes. But some visual regressions slip through — a
+missing table border, a 0.5pt colour shift, an anti-aliasing change.
+Pixel diff rasterises both PDFs and compares images, catching
+anything semantic diff misses.
+
+Pixel diff is one **mode** within the harness, not the whole diff
+strategy. It's expensive (~1s/page at 150 DPI; ~10s/page at 300 DPI)
+so it's opt-in via profile, not on by default.
+
+## Approach
+
+Files under `lib/arrolio/harness/pixel/`:
+
+- `rasteriser.rb` — wraps `pdftoppm` (poppler) to convert a PDF to a
+  PNG per page at configurable DPI. Falls back gracefully if
+  `pdftoppm` isn't installed.
+
+- `image_comparator.rb` — uses ImageMagick `compare` to compute a
+  per-page diff image and a similarity metric (0..1). Optionally
+  uses libvips for faster batch comparison.
+
+- `pixel_diff_report.rb` — value object: `per_page_similarity`
+  (Array of Float), `overall_similarity` (Float),
+  `diff_image_paths` (Array of paths to per-page diff PNGs).
+
+- `pixel_dimension.rb` — bridges into the comparator subsystem: a
+  `:pixel` dimension that contributes a `DiffNode` when similarity
+  drops below threshold (default 0.98 per page).
+
+- `html_embedder.rb` — when the HTML formatter (TODO 56) runs,
+  embeds the per-page diff images as base64 PNGs in the report.
+
+### Pipeline integration
+
+Pixel diff plugs into the comparator (TODO 55) as one more dimension:
+
+```ruby
+comparator = Comparator::PdfComparator.new(
+  profile: :visual_strict
+)
+# profile: :visual_strict includes :pixel dimension
+```
+
+### Heuristic thresholds
+
+- 1.0 similarity → identical; no diff.
+- ≥ 0.99 → informative (anti-aliasing noise).
+- 0.95..0.99 → flagged; usually a real but minor visual change.
+- < 0.95 → normative; almost certainly a visible regression.
+
+### CLI
+
+```sh
+# Run pixel diff alone
+arrolio-harness pixel-diff ours.pdf ref.pdf --dpi=150
+
+# Combined semantic + pixel diff
+arrolio-harness diff ours.pdf ref.pdf --profile=visual_strict
+```
+
+### CI integration
+
+- Rake task `rake harness:pixel_diff[fixture]` — runs against one
+  fixture.
+- Rake task `rake harness:pixel_diff_all` — runs against every
+  fixture; uploads the HTML report as a CI artifact.
+- Weekly CI job (not per-commit) due to runtime cost.
+
+## Done-When
+
+- [ ] Two identical PDFs produce overall similarity 1.0.
+- [ ] Two PDFs with one word different produce overall similarity
+      > 0.99 with a visible diff blob in the report.
+- [ ] Two PDFs with a colour change produce overall similarity >
+      0.95 with the changed region highlighted.
+- [ ] HTML report renders in a browser; diff images embedded as
+      base64.
+- [ ] The `:pixel` dimension integrates cleanly with the comparator.
+- [ ] If `pdftoppm`/ImageMagick isn't installed, the dimension
+      skips cleanly with a warning (no crash).
+- [ ] Profile `:visual_strict` includes pixel diff; `:strict` doesn't.

data/TODO.implementation/60-yard-documentation.md

@@ -0,0 +1,43 @@
+---
+priority: P3
+phase: 18
+depends_on: []
+layer: polish
+est: 2d
+status: pending
+---
+
+## Problem
+
+Arrolio needs API documentation for users who didn't write it. YARD
+is the standard Ruby doc tool. Every public class and method should
+have YARD docstrings; the docs should render cleanly to HTML.
+
+## Approach
+
+- Add `yard` gem to the development group.
+- `.yardopts` with `--no-private`, `--markup markdown`,
+  `--files CHANGELOG.md,LICENSE`, `--output-dir doc/yard`.
+- Add YARD docstrings to every public class and method:
+  - Module purpose statement at the top of each `lib/arrolio/*.rb`.
+  - Per-method: `# Brief description.` then `@param`, `@return`,
+    `@example`.
+  - Cross-link related classes with `{Class::Name}`.
+- Rake task `yard` to generate; `rake yard:serve` for live preview.
+
+Modules to document first (in order of API stability):
+1. `Arrolio` (top-level — the autoload tree, the `compose` shortcut).
+2. `Arrolio::Content::*` — content contract.
+3. `Arrolio::LayoutSpec::*` — layout spec.
+4. `Arrolio::Engine::Paged` — engine entry point.
+5. `Arrolio::Renderer::Pdf` — render entry point.
+6. `Arrolio::Composer` — high-level facade.
+7. `Arrolio::Oiml::*` — OIML pipeline (the main use case).
+
+## Done-When
+
+- [ ] `bundle exec yard` produces HTML in `doc/yard/`.
+- [ ] Every public method has a docstring.
+- [ ] No "Missing documentation" warnings from YARD on public API.
+- [ ] `Arrolio::Composer` is documented with a working example.
+- [ ] The README's quick-start links into the YARD docs.

data/TODO.implementation/61-benchmarks-and-stress-tests.md

@@ -0,0 +1,50 @@
+---
+priority: P3
+phase: 18
+depends_on: [54]
+layer: polish
+est: 2d
+status: pending
+---
+
+## Problem
+
+Need performance baselines to detect regressions and find hot paths.
+Also need to know Arrolio's behaviour on stress cases (very long
+documents, deep tables, thousands of paragraphs) before claiming
+production-ready.
+
+## Approach
+
+Files:
+
+- `benchmarks/bench.rb` — runs against a generated test document
+  (10, 50, 200 pages) and reports wall-clock per phase:
+  - Content tree construction.
+  - LayoutSpec construction.
+  - Flowable list construction.
+  - Engine::Paged layout.
+  - Renderer::Pdf render.
+  - Total.
+- Compares against `HexaPDF` (if installed) and FOP (if installed)
+  on the equivalent source.
+
+- `spec/arrolio/stress_spec.rb` — tagged `:stress`:
+  - 1000-page document lays out without crash.
+  - Memory after layout is < 500 MB.
+  - A 100-row table lays out across 5+ pages.
+  - A 100-item list lays out correctly.
+  - A document with 100 inline runs per paragraph lays out correctly.
+
+- Profiling: `stackprof` integration; `rake bench:profile` produces
+  a flamegraph.
+
+## Done-When
+
+- [ ] `rake bench` runs and prints per-phase timings.
+- [ ] A 100-page OIML-style document renders in < 30 seconds.
+- [ ] Memory stays bounded: 1000-page doc uses < 500 MB.
+- [ ] Hot paths identified; obvious inefficiencies fixed.
+- [ ] Stress specs pass under default RSpec config (not just `:stress`).
+- [ ] Benchmark history tracked in `benchmarks/history.csv` so
+      regressions are visible across commits.

data/TODO.implementation/62-validation-framework.md

@@ -0,0 +1,107 @@
+---
+priority: P1
+phase: 19
+depends_on: [22, 21]
+layer: conformance
+est: 3d
+status: pending
+---
+
+## Problem
+
+Modeled on `veraPDF/pdfa/validation/profiles/`, Arrolio needs a
+generic **rule-based validation framework**. A rule is `(id,
+applies_to, test_expression, severity, spec_reference)`. A profile
+is a collection of rules. Validation runs every rule over the
+document and produces `TestAssertion[]` (pass/fail per rule per
+location).
+
+Two consumers:
+
+1. **Self-validation** (Phase 19 layout rules, TODO 63): did
+   Arrolio itself produce a document free of layout regressions?
+2. **Conformance validation** (TODO 64): does the rendered PDF meet
+   PDF/A or PDF/UA spec requirements?
+
+## Approach
+
+Files under `lib/arrolio/conformance/`:
+
+- `rule.rb` — frozen value object:
+  ```ruby
+  Rule = Struct.new(:id, :applies_to, :test, :severity,
+                    :spec_reference, :tags, keyword_init: true)
+  ```
+  - `applies_to` — Symbol naming the target type
+    (`:page`, `:flowable`, `:table`, `:image`, `:document`).
+  - `test` — a `Proc` or DSL expression that returns `true`/`false`
+    given the target + context.
+  - `severity` — `:error`, `:warning`, `:info`.
+
+- `profile.rb` — collection of rules + metadata (name, version,
+  spec_link).
+
+- `test_assertion.rb` — frozen value object:
+  ```ruby
+  TestAssertion = Struct.new(:rule_id, :location, :status,
+                              :message, :evidence, keyword_init: true)
+  ```
+  - `status` — `:passed`, `:failed`, `:skipped`.
+  - `location` — `Location` (reuses TODO 57 source locator).
+
+- `validation_result.rb` — frozen value object:
+  - `profile` — the Profile applied.
+  - `assertions` — Array of TestAssertion.
+  - `compliant?` — true if no `:error` severity failed.
+  - `summary` — counts by status + severity.
+
+- `validator.rb` — runs a Profile over an `Output::Page[]` (or a
+  Pdfrb::Document):
+  ```ruby
+  class Arrolio::Conformance::Validator
+    def initialize(profile)
+    def validate(target) -> ValidationResult
+  end
+  ```
+
+- `profile_registry.rb` — name → Profile lookup. Built-in profiles
+  register at load.
+
+- `profile_loader.rb` — loads profiles from YAML or Ruby DSL.
+
+### YAML profile format
+
+```yaml
+name: oiml-render
+version: 1.0.0
+spec_reference: "OIML R-series style guide v3"
+rules:
+  - id: no-orphan-headings
+    applies_to: flowable
+    severity: error
+    test: |
+      target.kind == :heading && target.level <= 6 && !target.last_on_page?
+  - id: page-count-positive
+    applies_to: document
+    severity: error
+    test: "target.pages.length > 0"
+  - id: every-page-has-footer
+    applies_to: page
+    severity: warning
+    test: "target.region(:after).placed_boxes.any?"
+```
+
+The `test` expression is evaluated in a sandboxed context (no
+`eval`, no `send`); it's a small expression language with comparison,
+boolean, and method-call operators only.
+
+## Done-When
+
+- [ ] A profile with 1 trivial rule (page-count-positive) passes on
+      a valid doc, fails on an empty doc.
+- [ ] YAML loader produces equivalent Profile to Ruby DSL.
+- [ ] `Validator.validate(output_pages)` returns a ValidationResult.
+- [ ] `result.compliant?` is true iff no error-severity failures.
+- [ ] Each failed TestAssertion carries a Location pointing at the
+      offending page/box.
+- [ ] Spec coverage for happy path + every severity + YAML loading.