ucode 0.1.0 → 0.1.1

data/TODO.new/23-universal-glyph-set-source-map.md

@@ -0,0 +1,312 @@
+# 23 — Universal glyph set: Tier 1 source map
+
+## Goal
+
+Pin the canonical "one best font per Unicode 17 block" map as a
+first-class, versioned artifact. This is the single source of truth
+that drives the universal glyph set build (TODO 24) and the
+audit-against-universal-set pipeline (TODO 25).
+
+The resolver in TODO 20 reads this config; the build in TODO 21
+materializes it; audits in TODO 25 reference it. Without this file we
+have resolver mechanics but no opinionated, full-coverage font choice.
+
+## Why a separate file
+
+Embedding the block→font table inside the resolver (as TODO 20's
+example shows) blurs two concerns:
+
+1. **Mechanism** (the priority-ordered dispatch loop) — belongs in
+   `Resolver`. Stable across Unicode versions.
+2. **Policy** (which font wins for which block this Unicode version) —
+   belongs in a versioned data file. Changes every Unicode release.
+
+Lifting policy out into `config/unicode17_universal_glyph_set.yml`
+makes it reviewable on its own, diffable across versions, and editable
+without touching Ruby.
+
+## Files to create
+
+- `config/unicode17_universal_glyph_set.yml` — the curated map.
+- `lib/ucode/glyphs/source_config.rb` — loader/validator (returns a
+  frozen `SourceConfig` instance with `#fonts_for(block_id)`).
+- `lib/ucode/models/glyph_source.rb` — typed model for one entry in
+  the yaml (label, kind, path_or_fontist_name, priority, license).
+- `lib/ucode/models/glyph_source_map.rb` — typed model for the whole
+  yaml (top-level `unicode_version`, `map` keyed by block_id).
+- `spec/ucode/glyphs/source_config_spec.rb` — loader specs (real
+  fixtures, no doubles).
+- `spec/fixtures/glyph_source_map/minimal.yml` — small fixture.
+- `spec/fixtures/glyph_source_map/full.yml` — symlink or copy of the
+  production config (exercised by one smoke spec).
+
+## YAML shape
+
+```yaml
+# config/unicode17_universal_glyph_set.yml
+unicode_version: "17.0.0"
+ucode_version: "0.2.0"
+generated_at: "2026-06-27T12:00:00Z"
+
+# Block IDs use the verbatim Unicode original name with underscores
+# (same convention as Blocks.txt folder names). One entry per block;
+# the resolver tries fonts in listed order.
+map:
+  Basic_Latin:
+    sources:
+      - kind: fontist
+        label: noto-sans
+        priority: 1
+        license: OFL
+        provenance: "Google Noto Sans, system fallback for Latin"
+      - kind: path
+        label: system-ui
+        path: "/System/Library/Fonts/Helvetica.ttc"
+        priority: 2
+        license: PROPRIETARY
+        provenance: "macOS system font, fallback only"
+
+  Greek_And_Coptic:
+    sources:
+      - kind: fontist
+        label: noto-sans
+        priority: 1
+
+  CJK_Unified_Ideographs:
+    sources:
+      - kind: path
+        label: FSung-1
+        path: "~/Downloads/全宋體/FSung-1.ttf"
+        priority: 1
+        license: OFL
+        provenance: "Taiwan MOE 全宋體, covers U+4E00..U+9FFF core"
+      - kind: path
+        label: FSung-2
+        path: "~/Downloads/全宋體/FSung-2.ttf"
+        priority: 2
+      # ... FSung-3 .. FSung-X cover the rest of CJK + extensions
+      - kind: fontist
+        label: noto-sans-cjk-jp
+        priority: 99
+        provenance: "Catch-all fallback for any CJK codepoint FSung misses"
+
+  CJK_Unified_Ideographs_Extension_J:
+    sources:
+      - kind: path
+        label: FSung-J
+        path: "~/Downloads/全宋體/FSung-J.ttf"
+        priority: 1
+      - kind: fontist
+        label: noto-sans-cjk-jp
+        priority: 2
+
+  Sidetic:
+    sources:
+      - kind: fontist
+        label: lentariso
+        priority: 1
+        license: OFL
+        provenance: "Lentariso ≥1.029 (github.com/Bry10022/Lentariso)"
+      - kind: fontist
+        label: noto-sans-sidetic
+        priority: 2
+
+  Beria_Erfe:
+    sources:
+      - kind: fontist
+        label: kedebideri
+        priority: 1
+        license: OFL
+        provenance: "Kedebideri 3.001 (software.sil.org/kedebideri)"
+
+  Tai_Yo:
+    sources:
+      - kind: path
+        label: NotoSerifTaiYo
+        path: "data/fonts/NotoSerifTaiYo.ttf"
+        priority: 1
+        license: OFL
+        provenance: "translationcommons.org, proven via correlate-v4"
+
+  Tolong_Siki:
+    sources:
+      - kind: fontist
+        label: noto-sans-tolong-siki
+        priority: 1
+
+  Sharada_Supplement:
+    sources:
+      - kind: fontist
+        label: noto-sans-sharada
+        priority: 1
+
+  Egyptian_Hieroglyphs:
+    sources:
+      - kind: path
+        label: UniHieroglyphica
+        path: "data/fonts/UniHieroglyphica.ttf"
+        priority: 1
+        license: OFL
+        provenance: "suignard.com, authoritative for Egyptian Hieroglyphs"
+
+  Egyptian_Hieroglyphs_Format_Controls:
+    sources:
+      - kind: path
+        label: Egyptian-Text
+        path: "data/fonts/EgyptianText-Regular.ttf"
+        priority: 1
+        license: OFL
+        provenance: "microsoft/font-tools, OFL"
+
+  Egyptian_Hieroglyphs_Extended_A:
+    sources:
+      - kind: path
+        label: UniHieroglyphica
+        path: "data/fonts/UniHieroglyphica.ttf"
+        priority: 1
+
+  Egyptian_Hieroglyphs_Extended_B:
+    sources:
+      - kind: path
+        label: UniHieroglyphica
+        path: "data/fonts/UniHieroglyphica.ttf"
+        priority: 1
+
+  Symbols_for_Legacy_Computing_Supplement:
+    sources:
+      - kind: fontist
+        label: babelstone-pseudographica
+        priority: 1
+        provenance: "BabelStone, partial Unicode 17 coverage"
+
+  Supplemental_Arrows_C:
+    sources:
+      - kind: fontist
+        label: symbola
+        priority: 1
+
+  Alchemical_Symbols:
+    sources:
+      - kind: fontist
+        label: noto-sans-symbols
+        priority: 1
+      - kind: fontist
+        label: symbola
+        priority: 2
+
+  Miscellaneous_Symbols_Supplement:
+    sources:
+      - kind: fontist
+        label: noto-sans-symbols-2
+        priority: 1
+
+  Musical_Symbols:
+    sources:
+      - kind: fontist
+        label: noto-music
+        priority: 1
+
+  Tangut:
+  Tangut_Supplement:
+  Tangut_Components:
+    sources:
+      - kind: fontist
+        label: noto-sans-tangut
+        priority: 1
+
+  Adlam:
+    sources:
+      - kind: fontist
+        label: noto-sans-adlam
+        priority: 1
+
+  # ... one entry per Unicode 17 block (~340 total) ...
+
+# Blocks with no known Tier 1 font. The resolver falls through to
+# Pillar 1 → Pillar 2 → Pillar 3 for these. Listed here for explicit
+# documentation; resolver treats absent block_id same as empty sources.
+no_tier1_font:
+  - Combining_Diacritical_Marks_Extended  # additions: font support spotty
+```
+
+## Source kinds
+
+- `fontist` — fontist-resolvable name. `FontLocator` finds/installs.
+- `path` — explicit filesystem path. Used for local-only fonts
+  (FSung, NotoSerifTaiYo before upstreaming).
+- `system` — system font via fontist's system index (macOS `/System`,
+  Linux `/usr/share/fonts`). Reserve for fallbacks.
+
+`priority` is a per-block integer; lower wins. The resolver iterates
+the block's `sources` in priority order; first hit wins.
+
+## Curation rules
+
+1. **One font per script family where possible.** Don't list three
+   Latin fonts; pick one (Noto Sans) and let pillar 1-3 catch misses.
+2. **CJK is the exception** — FSung is split across many files; one
+   entry per file with monotonic priority. The resolver loads all
+   of them; `fontist` fallback ensures the long tail still hits.
+3. **Proprietary fonts never ship.** Sources with `license:
+   PROPRIETARY` are loaded for glyph extraction only; the extracted
+   SVG (open data) ships, the font file does not.
+4. **Provenance is mandatory.** Every entry cites where the font comes
+   from and why it's the chosen source. Without provenance, the entry
+   is unreviewable.
+5. **Versioned.** Bump `ucode_version` field on every config edit.
+   Consumers can detect config drift vs the dataset.
+
+## Source config loader
+
+```ruby
+class Ucode::Glyphs::SourceConfig
+  # @param yaml_path [Pathname]
+  # @return [Ucode::Models::GlyphSourceMap]
+  def self.load(yaml_path = DEFAULT_PATH)
+    parsed = YAML.safe_load(yaml_path.read)
+    Ucode::Models::GlyphSourceMap.from_hash(parsed)
+  end
+
+  DEFAULT_PATH = Pathname.new("config/unicode17_universal_glyph_set.yml")
+end
+```
+
+The loader validates:
+- `unicode_version` matches the active UCD baseline (`Ucode.configuration.unicode_version`).
+- Every block_id in `Blocks.txt` has an entry (empty `sources:` allowed).
+- Every `path:` resolves to an existing file (warning, not error, for
+  paths under `~/Downloads` since those are user-local).
+- Every `fontist:` label is known to fontist's index (warning if not).
+
+## Acceptance
+
+- `config/unicode17_universal_glyph_set.yml` exists with one entry per
+  Unicode 17 block (~340 entries).
+- Every Unicode 17 new block (Sidetic, Beria Erfe, Tai Yo, Tolong
+  Siki, Sharada Supplement, CJK Ext J, Symbols Legacy Supp, Supp
+  Arrows-C, Alchemical Symbols ext, Misc Symbols Supp, Musical Symbols
+  Supp) has at least one Tier 1 source.
+- Every Egyptian Hieroglyphs block has UniHieroglyphica + Egyptian
+  Text entries.
+- Loader specs cover: happy path, missing block (warn), invalid yaml
+  (raise), missing font file (warn).
+- Smoke spec against `full.yml` confirms the file parses and every
+  block_id resolves to a `GlyphSource` array.
+- Rubocop clean.
+
+## Out of scope
+
+- The resolver mechanics — TODO 20.
+- The build that materializes glyphs from this config — TODO 24.
+- The audit pipeline that uses the universal set as reference — TODO 25.
+- Pillar 1/2/3 sources — these are not in the yaml; the resolver
+  appends them implicitly as fallbacks after Tier 1 sources.
+
+## References
+
+- Resolver mechanics: `TODO.new/20-canonical-resolver-4-tier.md`
+- Universal build: `TODO.new/24-universal-glyph-set-build.md`
+- Baseline data: `TODO.new/05-baseline-unicode17-coverage-audit.md`
+- Architecture: `docs/architecture.md` §"The 4-tier glyph sourcing
+  strategy"
+- FontLocator: `lib/ucode/glyphs/real_fonts/font_locator.rb`

data/TODO.new/24-universal-glyph-set-build.md

@@ -0,0 +1,189 @@
+# 24 — Universal glyph set build
+
+## Goal
+
+Materialize the universal glyph set: one SVG file per assigned Unicode
+17 codepoint, sourced via the 4-tier resolver using the curated Tier 1
+config from TODO 23. The set is the canonical reference for "what
+Unicode 17 looks like" — every codepoint has exactly one glyph, with
+documented provenance.
+
+This is Part 1 of the user's three-part directive: build the FULL base
+with full coverage so it can serve as the reference for font audits.
+
+## What "universal" means
+
+The universal set is:
+
+- **Total**: every assigned codepoint has a glyph.
+- **Single-sourced**: exactly one glyph per codepoint (no alternatives).
+- **Provenance-tagged**: each glyph records its tier + source font.
+- **Stable**: re-running with the same config + Unicode version
+  produces byte-identical SVGs.
+- **Public**: derived SVGs are open data even when the source font is
+  proprietary.
+
+The set is distinct from the per-codepoint Mode 1 dataset (TODO 21).
+Mode 1 puts glyph.svg inside each codepoint's directory along with
+full UCD properties. The universal set is glyph-only, in a flat
+layout, designed for fast lookup by audits.
+
+## Files to create
+
+```
+lib/ucode/glyphs/universal_set.rb              # namespace hub
+lib/ucode/glyphs/universal_set/builder.rb      # iterates codepoints, calls resolver, writes
+lib/ucode/glyphs/universal_set/manifest.rb     # builds manifest.json with provenance rollup
+lib/ucode/glyphs/universal_set/idempotency.rb  # mtime + content-hash check
+lib/ucode/models/universal_set_entry.rb        # one manifest entry
+lib/ucode/models/universal_set_manifest.rb     # full manifest model
+lib/ucode/commands/universal_set.rb            # CLI: bin/ucode universal-set build
+spec/ucode/glyphs/universal_set/builder_spec.rb
+spec/ucode/glyphs/universal_set/manifest_spec.rb
+spec/ucode/commands/universal_set_spec.rb
+spec/fixtures/universal_set/minimal/           # small slice for fixture-driven specs
+```
+
+## Output layout
+
+```
+output/universal_glyph_set/
+├── manifest.json                 # one entry per codepoint with provenance
+├── glyphs/
+│   ├── U+0000.svg
+│   ├── U+0001.svg
+│   ├── ...
+│   ├── U+1F6A0.svg
+│   └── ...
+└── reports/
+    ├── by_tier.json              # tier-1: N1, pillar-1: N2, ...
+    ├── by_block.json             # per-block tier breakdown
+    └── gaps.json                 # assigned codepoints with no glyph (should be empty)
+```
+
+Filename pattern: `<U+XXXX>.svg` with uppercase hex, zero-padded to 4
+digits (6 for codepoints above U+FFFF). Same convention as Mode 1.
+
+## Manifest shape
+
+```json
+{
+  "unicode_version": "17.0.0",
+  "ucode_version": "0.2.0",
+  "generated_at": "2026-06-27T12:00:00Z",
+  "source_config_sha256": "abc...",
+  "totals": {
+    "codepoints_assigned": 150012,
+    "codepoints_built": 150012,
+    "codepoints_skipped": 0,
+    "codepoints_failed": 0
+  },
+  "by_tier": {
+    "tier-1": 148512,
+    "pillar-1": 800,
+    "pillar-2": 200,
+    "pillar-3": 1500
+  },
+  "entries": [
+    { "codepoint": 65, "id": "U+0041", "tier": "tier-1",
+      "source": "noto-sans", "svg_sha256": "def...",
+      "svg_size_bytes": 412 },
+    { "codepoint": 10980, "id": "U+2AC4", "tier": "tier-1",
+      "source": "lentariso", "svg_sha256": "...",
+      "svg_size_bytes": 1820 },
+    ...
+  ]
+}
+```
+
+The manifest is the single index into the set. Audits (TODO 25) read
+the manifest, not the SVGs, for the "is this codepoint in the
+universal set?" check.
+
+## Build flow
+
+```ruby
+builder = Ucode::Glyphs::UniversalSet::Builder.new(
+  output_root: Pathname.new("output/universal_glyph_set"),
+  resolver: Ucode::Glyphs::Resolver.new(sources: resolver_sources),
+  unicode_version: "17.0.0",
+  parallel_workers: Ucode.configuration.parallel_workers,
+)
+builder.build
+```
+
+The builder:
+
+1. Reads the assigned-codepoints list from the active UCD baseline.
+2. For each codepoint, calls `resolver.resolve(codepoint)` → `Result`.
+3. Writes `glyphs/<U+XXXX>.svg` atomically (reuse
+   `Ucode::Repo::AtomicWrites`).
+4. Records the entry in the manifest.
+5. Emits the manifest + reports at the end.
+
+Idempotency follows Mode 1's pattern: a codepoint whose source font
+mtime + content hash are unchanged is skipped. Re-running with one
+new Tier 1 font re-resolves only the codepoints the new font covers.
+
+## CLI
+
+```bash
+bin/ucode universal-set build \
+  --version 17.0.0 \
+  --source-config config/unicode17_universal_glyph_set.yml \
+  --output output/universal_glyph_set \
+  [--parallel 8] \
+  [--block Sidetic]                # optional: build only one block
+```
+
+Output: stdout reports progress; final manifest at the output root.
+
+## Provenance recording
+
+Every `Result` from the resolver carries `tier` and `provenance`. The
+builder copies these into the manifest entry. Per-tier counts are
+rolled up from the entry list.
+
+Special: pillar 3 (Last Resort) glyphs are visually identical tofu
+boxes; their `provenance` is `"pillar-3:last-resort"` and their
+`source` field records the Last Resort UFO version. This makes pillar
+3 coverage visible in the audit drill-down (TODO 26) so users know
+"this glyph is a placeholder; we don't have a real outline."
+
+## Acceptance
+
+- `bin/ucode universal-set build` completes against Unicode 17.0
+  without errors.
+- `output/universal_glyph_set/manifest.json` shows
+  `codepoints_built == codepoints_assigned`.
+- `reports/gaps.json` is empty (or documents each gap with a reason).
+- Re-running with no source changes produces zero file writes
+  (idempotency check).
+- `--block Sidetic` produces only the Sidetic glyphs (~26 files);
+  manifest reflects the partial build.
+- A new Tier 1 font addition (e.g. adding a Sidetic font) re-resolves
+  only Sidetic; manifest delta shows old pillar-1 entries flipping to
+  tier-1.
+- Specs cover: builder happy path (small fixture set), idempotency,
+  per-block scoping, manifest serialization round-trip.
+- Rubocop clean.
+
+## Out of scope
+
+- The Tier 1 source config (TODO 23).
+- Resolver mechanics (TODO 20).
+- Audits that consume the set (TODO 25).
+- Per-codepoint Mode 1 dataset (TODO 21). The universal set is
+  separate; it does not replace Mode 1.
+- Site rendering of the universal set (that's a TODO 26 / fontist.org
+  concern).
+
+## References
+
+- Source config: `TODO.new/23-universal-glyph-set-source-map.md`
+- Resolver: `TODO.new/20-canonical-resolver-4-tier.md`
+- Mode 1 build: `TODO.new/21-canonical-unicode17-build.md`
+- Audit consumer: `TODO.new/25-font-audit-against-universal-set.md`
+- AtomicWrites: `lib/ucode/repo/atomic_writes.rb`
+- Existing pillar implementations: `lib/ucode/glyphs/{real_fonts,
+  embedded_fonts,last_resort}/`

data/TODO.new/25-font-audit-against-universal-set.md

@@ -0,0 +1,195 @@
+# 25 — Font audit against universal set
+
+## Goal
+
+Replace the current cmap-vs-UCD coverage audit with a cmap-vs-universal-set
+audit. The font's coverage is now compared against the universal glyph set
+(TODO 24) — one glyph per assigned codepoint — instead of against the
+abstract UCD codepoint list.
+
+This is Part 2 of the user's three-part directive. The universal set
+becomes the reference for "what could be rendered." A font's coverage
+report shows not just "1,500 codepoints covered" but "1,500 of the
+150,012 Unicode-17-representable glyphs."
+
+## Why universal-set reference, not UCD codepoint list
+
+Today's audit (TODOs 04, 11, 13) compares a font's cmap against the
+abstract set of assigned Unicode 17 codepoints. That's correct but
+abstract — a consumer can't see "what does the missing codepoint
+look like?"
+
+By comparing against the universal glyph set instead:
+
+- Every "missing" codepoint has a renderable glyph the consumer can
+  preview (TODO 26).
+- Tier provenance is visible: "this font is missing U+10980 SIDETIC
+  LETTER A, which the universal set sources from Lentariso."
+- Audits across fonts are directly comparable: two fonts both missing
+  "all of Sidetic" show the same gap, in the same way.
+
+Mechanically, the universal set's codepoint list == the assigned
+codepoint list. The audit logic is identical; the difference is that
+every codepoint has an attached glyph + provenance that the renderer
+(TODO 14, TODO 26) can surface.
+
+## Files to create / change
+
+- `lib/ucode/audit/universal_set_reference.rb` — adapter that wraps
+  the universal-set manifest as a `CoverageReference` (interface below).
+- `lib/ucode/audit/coverage_reference.rb` — common interface for any
+  "what's the assigned codepoint set" reference (UCD-only and
+  universal-set both implement).
+- `lib/ucode/audit/extractors/aggregations.rb` — change to accept a
+  `CoverageReference` instead of always reading UCD directly. Default:
+  universal-set reference if available; fall back to UCD-only.
+- `lib/ucode/audit/face_auditor.rb` — accept `reference:` kwarg;
+  thread it through to extractors.
+- `lib/ucode/audit/library_auditor.rb` — same.
+- `lib/ucode/commands/audit.rb` (new, was originally going to be TODO
+  16's CLI) — `ucode audit font` now takes
+  `--reference-universal-set=<path>` flag (default: enabled if the
+  universal set exists).
+- Specs:
+  - `spec/ucode/audit/universal_set_reference_spec.rb`
+  - `spec/ucode/audit/extractors/aggregations_with_universal_set_spec.rb`
+  - `spec/ucode/commands/audit_with_universal_set_spec.rb`
+
+## CoverageReference interface
+
+```ruby
+class Ucode::Audit::CoverageReference
+  Entry = Struct.new(:codepoint, :id, :tier, :source, keyword_init: true)
+
+  # @param codepoint [Integer]
+  # @return [Boolean]
+  def include?(codepoint)
+    raise NotImplementedError
+  end
+
+  # @param block_id [String] verbatim block name
+  # @return [Array<Entry>] every assigned codepoint in the block,
+  #   with tier + source from the universal-set manifest
+  def entries_for_block(block_id)
+    raise NotImplementedError
+  end
+
+  # @return [String] e.g. "ucd-17.0.0", "universal-set:17.0.0:sha256"
+  def reference_id
+    raise NotImplementedError
+  end
+
+  # @return [Hash{String=>String}] provenance metadata for the report
+  def baseline_metadata
+    raise NotImplementedError
+  end
+end
+```
+
+Two concrete implementations:
+
+- `Ucode::Audit::UcdOnlyReference` — reads `Blocks.txt` and assigned
+  codepoints from the active UCD database. Entry.tier/source are nil.
+- `Ucode::Audit::UniversalSetReference` — reads the universal-set
+  manifest (TODO 24). Every entry carries tier + source.
+
+## Aggregation changes
+
+`BlockAggregator` previously took `block_total_assigned:` integer from
+the UCD-only baseline. It now takes a `CoverageReference` and calls
+`reference.entries_for_block(block_id)` to get the per-codepoint list.
+For each codepoint, the per-block summary includes:
+
+- `covered_count` — codepoints in this block that the font's cmap covers.
+- `missing_codepoints` — codepoints in this block that the font's cmap
+  does NOT cover, with universal-set entry attached for renderer drill-down.
+
+The `AuditReport.baseline` field gains a `reference_kind` ("ucd" or
+"universal-set") so consumers know which kind of reference produced
+the per-block counts.
+
+## Report shape delta
+
+Existing `block_summaries[i]` (per TODO 03 + 04) carries
+`missing_codepoints: [Integer]`. New optional field per
+`BlockSummary`:
+
+```json
+{
+  "name": "Sidetic",
+  ...
+  "missing_codepoints": [10981, 10982, ...],
+  "missing_codepoint_provenance": [
+    { "codepoint": 10981, "tier": "tier-1", "source": "lentariso" },
+    ...
+  ]
+}
+```
+
+`missing_codepoint_provenance` is only populated when the reference is
+a UniversalSetReference. UcdOnlyReference produces the existing
+schema (no provenance).
+
+This is an additive change. Old consumers ignore the new field. The
+contract (TODO 04) calls this out as a minor version bump.
+
+## Backwards compatibility
+
+- `ucode audit font` without a universal set behaves exactly as today
+  (UCD-only reference).
+- `ucode audit font` with `--reference-universal-set=<path>` switches
+  to universal-set reference. The default is to look for the manifest
+  at `output/universal_glyph_set/manifest.json`; if present, use it;
+  if absent, warn and fall back to UCD-only.
+
+This means CI runs that haven't built the universal set yet continue
+to pass. The new functionality is opt-in via presence of the manifest.
+
+## Cross-font comparison
+
+A new optional output: `output/font_audit/_comparison/<label1>_vs_<label2>.json`
+produced by:
+
+```bash
+bin/ucode audit compare <label1> <label2>
+```
+
+Diffs two audits: same blocks, same codepoints, but coverage cells
+differ. Powers "Inter covers these N codepoints that Arial misses"
+visualizations on fontist.org.
+
+Implementation: extends `Ucode::Audit::Differ` to compare two
+`AuditReport`s at the codepoint level (current `Differ` compares
+fields and structural inventories; new mode compares per-block
+coverage).
+
+## Acceptance
+
+- `UniversalSetReference` round-trips the universal-set manifest into
+  the CoverageReference interface correctly (specs).
+- `FaceAuditor` accepts `reference:` kwarg; defaults to UCD-only when
+  omitted.
+- `BlockAggregator` produces `missing_codepoint_provenance` when given
+  a UniversalSetReference; omits the field for UcdOnlyReference.
+- `bin/ucode audit font <path> --reference-universal-set=<manifest>`
+  produces a report where every missing codepoint carries provenance.
+- `bin/ucode audit font <path>` (no flag, no manifest on disk) is
+  byte-identical to today's output (regression check).
+- `bin/ucode audit compare` produces a per-block per-codepoint diff.
+- Rubocop clean.
+
+## Out of scope
+
+- The drill-down HTML view that renders the universal glyphs next to
+  each missing codepoint — TODO 26.
+- The fontist.org consumer side that surfaces the new field — TODO 27.
+- The universal set build itself — TODO 24.
+
+## References
+
+- Universal set build: `TODO.new/24-universal-glyph-set-build.md`
+- HTML browser: `TODO.new/14-html-face-browser.md`
+- fontist.org contract: `TODO.new/04-fontist-org-contract.md`
+- Existing Differ: `lib/ucode/audit/differ.rb`
+- Existing aggregations extractor:
+  `lib/ucode/audit/extractors/aggregations.rb`