ucode 0.1.0

data/TODO.new/15-html-library-browser.md

@@ -0,0 +1,102 @@
+# 15 — HTML library browser
+
+## Goal
+
+Generate a library-level `index.html` that lists all audited fonts as
+cards with summary stats, linking into each face's per-face
+`index.html` (from TODO 14).
+
+This is the "simple HTML browser" for browsing multiple audits
+locally. Open one file, see all audited fonts, click into any one.
+
+## Files to create
+
+- `lib/ucode/audit/browser/library_page.rb` — renders the library index.
+- `lib/ucode/audit/browser/templates/library.html.erb`.
+- `lib/ucode/audit/browser/templates/library.css` — inlined.
+- `lib/ucode/audit/browser/templates/library.js` — inlined; minimal.
+- `spec/ucode/audit/browser/library_page_spec.rb`.
+
+## When this runs
+
+The library browser is generated at the parent level when:
+
+- `ucode audit library <dir>` runs (audits a directory of fonts).
+- `ucode audit browser --input output/font_audit` runs (regenerates
+  browser HTML from existing audits without re-auditing).
+
+Both invocations should produce (or update) `output/font_audit/index.html`.
+
+## Template structure
+
+### Header
+
+- Library summary stats: total fonts audited, total codepoints across
+  all fonts (with double-counting note), date range of audits, ucode
+  version.
+
+### Filter / sort controls
+
+Lightweight, vanilla JS:
+
+- Search box (filter by family name or postscript name).
+- Sort dropdown: by name / by coverage % / by codepoint count / by
+  audit date.
+- Filter by status: complete only / partial only / has discrepancies.
+
+### Card grid
+
+One card per audited font. Each card shows:
+
+- Font name (large).
+- Foundry + version (small).
+- Coverage bar (visual: % of baseline covered).
+- Quick stats: `2,857 cps / 24 blocks / 5 scripts`.
+- Status badges: COMPLETE blocks count, PARTIAL blocks count,
+  DISCREPANCIES (if any).
+- "Open" link → `<label>/index.html`.
+
+Clicking the card opens the face's per-face browser.
+
+### Optional: comparison view
+
+Out of scope for v1. The card grid is the v1 deliverable; comparison
+(a la `ucode audit compare` but visual) can come later as a separate
+TODO.
+
+## Inline data
+
+Same pattern as TODO 14: inline the library summary JSON into a
+`<script type="application/json" id="library-overview">` block so the
+page renders without any fetch. The summary is small (one entry per
+font; even 1,000 fonts × 200 bytes ≈ 200KB).
+
+## JS behavior
+
+~100 lines vanilla JS:
+
+- Read inlined overview.
+- Render card grid.
+- Wire search/sort/filter to re-render on input.
+- Open card click → navigate to `<label>/index.html`.
+
+No lazy fetching needed at the library level — all data is inlined.
+
+## Acceptance
+
+- `Ucode::Audit::Browser::LibraryPage.new(reports:, output_root:).write`
+  produces `<output_root>/index.html`.
+- The page lists all input reports as cards.
+- Search/sort/filter work without page reload.
+- Clicking a card navigates to that face's per-face page.
+- Library page is fully self-contained (no external resources).
+- Spec asserts the page contains each font's family name and the
+  total font count.
+- Rubocop clean.
+
+## References
+
+- Face browser: `TODO.new/14-html-face-browser.md`
+- Emitter (library mode): `TODO.new/13-directory-emitter.md`
+- CLI: `TODO.new/16-cli-audit-subcommands.md` (`ucode audit library`
+  auto-generates this; `ucode audit browser` regenerates)

data/TODO.new/16-cli-audit-subcommands.md

@@ -0,0 +1,142 @@
+# 16 — CLI audit subcommands
+
+## Goal
+
+Wire the audit pipeline to `bin/ucode` as a unified `ucode audit`
+namespace. Replace `ucode font-coverage` (the v0.1 name). The CLI is
+a thin Thor front-end; real logic lives in `Ucode::Commands::Audit::*Command`.
+
+## Files to create
+
+- `lib/ucode/commands/audit_font_command.rb`
+- `lib/ucode/commands/audit_collection_command.rb`
+- `lib/ucode/commands/audit_library_command.rb`
+- `lib/ucode/commands/audit_compare_command.rb`
+- `lib/ucode/commands/audit_browser_command.rb`
+- Update `lib/ucode/cli.rb` to register the new `audit` namespace.
+
+Plus specs for each command (in-process, no shell-out).
+
+## CLI surface
+
+### `ucode audit font PATH [options]`
+
+Single face audit. PATH is a font file or a fontist-resolvable name
+(`label=/path/to/font.ttf` for direct, bare name for fontist find).
+
+Options:
+- `--label LABEL` — output directory name (default: postscript_name or font file basename).
+- `--unicode-version VERSION` — baseline version (default: ucode's default).
+- `--verbose` — emit per-codepoint detail under `codepoints/`.
+- `--with-glyphs` — emit per-codepoint SVG under `glyphs/` (renders from audited font).
+- `--brief` — cheap-extractor-only mode.
+- `--output DIR` — output root (default: `output/font_audit`).
+- `--browse` — also generate the face HTML browser.
+- `--format text|json|yaml` — stdout format when no `--output`.
+
+Output: `<output>/<label>/` directory tree (per TODO 13).
+
+### `ucode audit collection PATH [options]`
+
+TTC/OTC/dfong. Same options as `audit font` plus:
+
+- `--font-index N` — audit only face N (output behaves like single face).
+
+Output: `<output>/<source_label>/00-<face>/...` per TODO 13.
+
+### `ucode audit library DIR [options]`
+
+Walk a directory of fonts (recursive optional).
+
+Options:
+- `--recursive` — walk into subdirectories.
+- `--parallel N` — parallel face audits (default: ucode's default).
+- All `audit font` options apply per-face.
+- `--browse` — also generate the library HTML browser at `<output>/index.html`.
+
+Output: per-face directories + library-level index.
+
+### `ucode audit compare LEFT RIGHT [options]`
+
+Diff two audits. LEFT and RIGHT each may be:
+
+- A path to a font file (audited on-the-fly).
+- A path to a saved audit directory (reads its `index.json`).
+- A path to a saved `index.json` directly.
+
+Options:
+- `--format text|json` — output format.
+- `--output FILE` — write to file (default: stdout).
+
+Output: `AuditDiff` rendered via TODO 12.
+
+### `ucode audit browser [options]`
+
+Regenerate HTML browsers from existing JSON audits.
+
+Options:
+- `--input DIR` — audit root (default: `output/font_audit`).
+- `--faces-only` — regenerate per-face `index.html` only.
+- `--library-only` — regenerate library-level `index.html` only.
+
+Output: HTML files only; no JSON rewrites.
+
+## Rename of `ucode font-coverage`
+
+`ucode font-coverage` is removed (not aliased) — nothing external
+depends on it yet. The current `RealFonts` subsystem that powers it
+becomes the `Ucode::Audit::FontLocator` + `Ucode::Audit::CoverageAuditor`
+internally; the CLI surface is the new `audit` namespace.
+
+`output/font_coverage/` directory name is renamed to
+`output/font_audit/` in the same PR. Anyone with stale output from
+v0.1 can delete it manually.
+
+## Command class pattern
+
+Each `Commands::Audit::*Command` is a pure Ruby class with a `#run`
+method. No Thor knowledge inside. Thor (in `lib/ucode/cli.rb`) just
+parses args and constructs the command. This pattern matches the
+existing `Ucode::Commands::*Command` classes.
+
+```ruby
+module Ucode
+  module Commands
+    class AuditFontCommand
+      def initialize(font_path, label:, unicode_version:, verbose:, with_glyphs:, brief:, output_root:, browse:)
+        # ...
+      end
+
+      def run
+        # Resolve font, build Context, run extractors, emit.
+      end
+    end
+  end
+end
+```
+
+## Acceptance
+
+- All 5 commands exist and are spec'd in-process.
+- `ucode audit font <fixture.ttf>` produces the directory tree at
+  `output/font_audit/<label>/`.
+- `ucode audit font <fixture.ttf> --browse` additionally produces
+  `index.html` that opens correctly.
+- `ucode audit collection <fixture.ttc>` produces one tree per face.
+- `ucode audit library spec/fixtures/fonts/` audits every fixture font
+  and produces a library-level index.
+- `ucode audit compare` works with all three input forms (font,
+  directory, json file).
+- `ucode audit browser` regenerates HTML without re-auditing.
+- `ucode font-coverage` is gone (verified: `bin/ucode help` does not
+  list it).
+- No `double()` in specs.
+- Rubocop clean.
+
+## References
+
+- Architecture: `docs/architecture.md` §"CLI"
+- Existing CLI: `lib/ucode/cli.rb`, `lib/ucode/commands/`
+- All upstream TODOs: 06-15
+- Removed: `ucode font-coverage` (current implementation in
+  `lib/ucode/glyphs/real_fonts/` and the current CLI registration)

data/TODO.new/17-fontisan-cleanup-audit.md

@@ -0,0 +1,147 @@
+# 17 — Fontisan: delete audit subsystem
+
+## Goal
+
+After ucode's audit (TODOs 06-16) produces byte-equivalent or richer
+output, delete fontisan's audit subsystem. fontisan keeps only its
+font-parsing primitives.
+
+**Precondition:** ucode audit has shipped, been validated against
+real-world fonts, and fontist.org has confirmed the new contract
+works. Do NOT execute this TODO until those gates pass.
+
+## Files to delete in fontisan
+
+```
+fontisan/lib/fontisan/audit.rb
+fontisan/lib/fontisan/audit/                  # entire directory
+fontisan/lib/fontisan/commands/audit_command.rb
+fontisan/lib/fontisan/commands/audit_compare_command.rb
+fontisan/lib/fontisan/commands/audit_library_command.rb
+fontisan/lib/fontisan/models/audit.rb
+fontisan/lib/fontisan/models/audit/           # entire directory
+fontisan/lib/fontisan/formatters/audit_text_renderer.rb
+fontisan/lib/fontisan/formatters/audit_diff_text_renderer.rb
+fontisan/lib/fontisan/formatters/library_summary_text_renderer.rb
+fontisan/spec/commands/audit_command_spec.rb
+fontisan/spec/commands/audit_compare_command_spec.rb
+fontisan/spec/commands/audit_library_command_spec.rb
+fontisan/spec/audit/                          # entire directory
+fontisan/spec/models/audit/                   # entire directory
+fontisan/spec/formatters/                     # audit-related specs only
+fontisan/PROPOSAL.font-audit.md
+fontisan/TODO.audit/                          # entire directory
+```
+
+## Files to edit in fontisan
+
+### `fontisan/lib/fontisan/commands.rb`
+
+Remove the `autoload :AuditCommand` and similar lines.
+
+### `fontisan/lib/fontisan/models.rb`
+
+Remove the `autoload :Audit` line.
+
+### `fontisan/lib/fontisan/cli.rb`
+
+Remove the `audit`, `audit-compare`, `audit-library` Thor method
+registrations. Remove the `audit` namespace.
+
+### `fontisan/exe/fontisan`
+
+No direct changes — the CLI class dispatch handles it. Verify
+`fontisan help` no longer shows audit commands.
+
+### `fontisan/lib/fontisan/formatters.rb`
+
+Remove the audit-related autoloads.
+
+### `fontisan/README.adoc`
+
+Remove the `fontisan audit` section. Replace with a pointer to
+`ucode audit`:
+
+```adoc
+== Auditing fonts
+
+The font audit functionality (per-face coverage reports, library
+summaries, audit diffs) has moved to the `ucode` gem.
+
+  ucode audit font path/to/font.ttf
+  ucode audit library path/to/fonts/
+
+See https://github.com/fontist/ucode for the full audit documentation.
+```
+
+### `fontisan/CHANGELOG.md`
+
+Add entry under the next release:
+
+```markdown
+### Breaking
+- Removed `fontisan audit`, `fontisan audit-compare`, `fontisan audit-library`.
+  Migrated to the `ucode` gem. Run `ucode audit font <path>` instead.
+- Removed `Fontisan::Audit::*`, `Fontisan::Models::Audit::*`,
+  `Fontisan::Commands::AuditCommand`, and audit formatters. Use
+  `Ucode::Audit::*` instead.
+```
+
+### `fontisan/fontisan.gemspec`
+
+No changes — fontisan doesn't depend on ucode and shouldn't (ucode
+depends on fontisan for parsing).
+
+## Deprecation window
+
+Per `docs/FONTISAN_MIGRATION.md` convention: one release cycle of
+deprecation warnings before removal.
+
+- **Release N-1** (deprecation): the audit commands emit a one-line
+  warning on stderr: "fontisan audit is deprecated and will be removed
+  in fontisan X.Y; use `ucode audit` instead." Commands still work.
+- **Release N** (removal, this TODO): the commands are gone. Anyone
+  still calling them gets a clear `NoMethodError` / Thor "unknown
+  command" with the migration pointer.
+
+If the deprecation window has not yet been open in fontisan, do this
+TODO in two commits: first add the deprecation warnings, then (after
+a release cycle) delete the code.
+
+## Boundary preservation
+
+What stays in fontisan:
+
+- All font-parsing code (FontLoader, FormatDetector, sfnt_table,
+  glyf/CFF/name/cmap/OS-2/head/hhea/post/fpgm/prep/cvt/gasp/COLR/CPAL/
+  SVG/CBDT/CBLC/sbix/fvar/gvar/STAT/avar/GSUB/GPOS readers).
+- The existing non-audit commands (info, scripts, features, unicode,
+  convert, subset).
+- The existing non-audit formatters.
+
+If ucode's audit extractors call any fontisan internal that becomes
+unused after this TODO, leave it in fontisan anyway (it may have
+non-audit consumers we don't know about). ucode's API surface into
+fontisan is documented in `docs/FONTISAN_MIGRATION.md`.
+
+## Acceptance
+
+- `bundle exec fontisan help` shows no `audit` commands.
+- `bundle exec ruby -e "require 'fontisan'; Fontisan::Audit"` raises
+  NameError.
+- `bundle exec ruby -e "require 'fontisan'; Fontisan::Models::Audit"`
+  raises NameError.
+- `bundle exec rspec` in fontisan passes (no audit-spec failures
+  because the audit specs are also deleted).
+- `bundle exec rubocop` in fontisan clean (no dangling autoloads).
+- README + CHANGELOG updated.
+- No regressions in fontisan's non-audit test suite.
+
+## References
+
+- Pre-condition: TODOs 06-16 all merged and validated
+- ucode audit API surface: `docs/FONTISAN_MIGRATION.md`
+- Companion TODO: `TODO.new/18-fontisan-cleanup-ucd.md` (delete UCD
+  subsystem from fontisan; do this in the same PR or the immediate
+  next one)
+- Companion TODO: `TODO.new/19-fontisan-docs-update.md`

data/TODO.new/18-fontisan-cleanup-ucd.md

@@ -0,0 +1,156 @@
+# 18 — Fontisan: delete UCD subsystem
+
+## Goal
+
+Once fontisan's audit has moved to ucode (TODO 17) AND no other
+fontisan consumer uses fontisan's UCD code, delete fontisan's entire
+UCD subsystem. ucode becomes the sole UCD implementation across the
+fontist org.
+
+**Preconditions:**
+1. TODOs 06-17 merged. fontisan no longer has any audit code.
+2. `grep -r "Fontisan::Ucd" --include="*.rb"` across all fontist-org
+   repos returns zero hits in production code. (Run this grep
+   immediately before executing this TODO; if non-zero, stop and
+   migrate the stragglers first.)
+
+## Files to delete in fontisan
+
+```
+fontisan/lib/fontisan/ucd.rb
+fontisan/lib/fontisan/ucd/                   # entire directory
+  aggregator.rb
+  cache_manager.rb
+  download_error.rb
+  downloader.rb
+  version_resolver.rb
+  index_builder.rb
+  index.rb
+  database.rb
+  db_builder.rb
+  config/ucd.yml
+fontisan/lib/fontisan/models/ucd.rb
+fontisan/lib/fontisan/models/ucd/            # entire directory
+  ucd.rb
+  ucd_char.rb
+fontisan/lib/fontisan/cli/ucd_cli.rb
+fontisan/spec/ucd/                           # entire directory
+fontisan/spec/cli/ucd_cli_spec.rb
+fontisan/spec/models/ucd/                    # entire directory
+```
+
+## Files to edit in fontisan
+
+### `fontisan/lib/fontisan/models.rb`
+
+Remove the `autoload :Ucd` line.
+
+### `fontisan/lib/fontisan/cli.rb`
+
+Remove the `ucd` Thor subcommand registration.
+
+### `fontisan/exe/fontisan`
+
+No direct changes — CLI dispatch handles it. Verify `fontisan help` no
+longer shows `fontisan ucd`.
+
+### `fontisan/lib/fontisan.rb`
+
+Remove any UCD autoloads or requires.
+
+### `fontisan/fontisan.gemspec`
+
+Remove UCD-specific deps if any became unused (e.g. `nokogiri` if it
+was only for UCDXML parsing — check `grep -r "nokogiri" fontisan/lib`
+before removing).
+
+### `fontisan/README.adoc`
+
+Remove the `fontisan ucd` section. Add a pointer to ucode:
+
+```adoc
+== Unicode Character Database
+
+fontisan no longer carries its own UCD database or downloader. Use
+the `ucode` gem for UCD data, block/script lookups, and Unicode
+version resolution.
+
+  ucode cache list
+  ucode lookup block U+0041
+
+See https://github.com/fontist/ucode.
+```
+
+### `fontisan/CHANGELOG.md`
+
+```markdown
+### Breaking
+- Removed `fontisan ucd` CLI subcommand. Use `ucode` for UCD data.
+- Removed `Fontisan::Ucd::*` (CacheManager, Database, DbBuilder,
+  IndexBuilder, Index, Aggregator, Downloader, VersionResolver,
+  RangeEntry, Config, Errors).
+- Removed `Fontisan::Models::Ucd::*` (Ucd, UcdChar).
+- Removed automatic download of `ucd.all.flat.zip`.
+```
+
+## Deprecation window
+
+This is the second migration tracked in `docs/FONTISAN_MIGRATION.md`.
+The runbook there calls for a compat-shim release window (Phase B-D).
+Verify the shim has shipped and consumers have migrated before
+deleting.
+
+The compat shim at `fontisan/lib/fontisan/ucd.rb` (if shipped per
+`docs/guide/fontisan_migration.md`) is deleted in this TODO. The
+shim's job was to bridge `Fontisan::Ucd::*` calls to `Ucode::*`; once
+no callers remain, the shim is dead code.
+
+## Boundary preservation
+
+What stays in fontisan:
+
+- All font-parsing code (unchanged).
+- All non-audit, non-UCD commands (info, scripts, features, unicode,
+  convert, subset).
+
+Wait — `fontisan unicode` command. Does it depend on `Fontisan::Ucd`?
+Check before deleting. If yes, migrate it to use `Ucode::*` (and add
+`ucode` as a runtime dep of fontisan for this command only), OR move
+the command to ucode entirely.
+
+Pre-execution check: `grep -r "Fontisan::Ucd" fontisan/lib/fontisan/commands/`.
+If non-zero, address each caller first.
+
+## Cache cleanup
+
+Document for users that the old cache at
+`~/.config/fontisan/unicode/` is now stale and can be deleted:
+
+```bash
+rm -rf ~/.config/fontisan/unicode/
+```
+
+Add this to the CHANGELOG. Do NOT delete it programmatically — that's
+the user's disk and the user's call.
+
+## Acceptance
+
+- `bundle exec fontisan help` shows no `ucd` command.
+- `bundle exec ruby -e "require 'fontisan'; Fontisan::Ucd"` raises
+  NameError.
+- `bundle exec ruby -e "require 'fontisan'; Fontisan::Models::Ucd"`
+  raises NameError.
+- `find fontisan/lib -name "*.rb" -exec grep -l "Fontisan::Ucd" {} \;`
+  returns nothing.
+- `bundle exec rspec` in fontisan passes (no UCD-spec failures because
+  UCD specs are also deleted).
+- `bundle exec rubocop` in fontisan clean.
+- README + CHANGELOG updated.
+
+## References
+
+- Pre-condition: TODOs 06-17 merged
+- Migration runbook: `docs/FONTISAN_MIGRATION.md`
+- Migration guide: `docs/guide/fontisan_migration.md`
+- Companion: `TODO.new/17-fontisan-cleanup-audit.md` (do this first)
+- Companion: `TODO.new/19-fontisan-docs-update.md`

data/TODO.new/19-fontisan-docs-update.md

@@ -0,0 +1,155 @@
+# 19 — Fontisan: docs and shim update
+
+## Goal
+
+Update fontisan's docs to reflect the post-migration reality: ucode
+owns the audit and UCD subsystems; fontisan is a pure font parser.
+Also handle the compat-shim lifecycle (introduce, warn, remove).
+
+## Scope
+
+Three doc surfaces in fontisan need updating:
+
+1. `fontisan/README.adoc` — the main readme. Remove audit + UCD
+   sections; add "What moved to ucode" section.
+2. `fontisan/CHANGELOG.md` — breaking-change entries under the next
+   release.
+3. `fontisan/docs/` — any audit/UCD guides. Either delete or rewrite
+   as migration guides.
+
+Plus the compat-shim code (per `docs/FONTISAN_MIGRATION.md` Phase B-D)
+introduced ahead of TODOs 17-18.
+
+## Compat shim lifecycle
+
+Per `docs/FONTISAN_MIGRATION.md`:
+
+### Phase B (introduce shim, ahead of TODO 17-18)
+
+Add `fontisan/lib/fontisan/ucd.rb` and per-class shim files. Each shim
+delegates to `Ucode::*` and emits a deprecation warning on first
+access.
+
+Also add `fontisan/lib/fontisan/audit.rb` shim that delegates
+`Fontisan::Audit::*` and `Fontisan::Models::Audit::*` to
+`Ucode::Audit::*` and `Ucode::Models::Audit::*`.
+
+Add `ucode` as a runtime dep of fontisan in `fontisan.gemspec`:
+
+```ruby
+spec.add_dependency "ucode", "~> 0.2"
+```
+
+This is the only release where fontisan depends on ucode. The dep
+goes away when the shim is removed (TODO 17 + 18).
+
+### Phase C (one release cycle of warnings)
+
+User-facing callers see warnings on stderr:
+
+```
+fontisan: Fontisan::Ucd::CacheManager is deprecated; use Ucode::Cache.
+         Called from /path/to/caller.rb:42.
+```
+
+Track via the deprecation-warning tracker (often just a GitHub issue
+per quarter).
+
+### Phase D (TODOs 17 + 18 execute)
+
+Delete the shim. Remove the `ucode` runtime dep. The next fontisan
+release ships without audit or UCD code at all.
+
+## README rewrite outline
+
+```adoc
+= Fontisan
+
+Fontisan is a Ruby library for reading and manipulating font files
+(TrueType, OpenType, CFF, WOFF, WOFF2, TrueType Collection, Type 1).
+
+== What's here
+
+- Font loading + format detection.
+- Per-table readers: name, cmap, glyf, CFF, OS/2, head, hhea, post,
+  fpgm, prep, cvt, gasp, COLR, CPAL, SVG, CBDT, CBLC, sbix, fvar,
+  gvar, STAT, avar, GSUB, GPOS.
+- Subsetter, converter, validator.
+
+== What's not here (moved to ucode)
+
+The following functionality has migrated to the `ucode` gem:
+
+- *Font audit reports* (`fontisan audit`). Use `ucode audit font`.
+- *Unicode Character Database* (`fontisan ucd`). Use `ucode` directly
+  for UCD data, block/script lookup, and Unicode version resolution.
+
+See https://github.com/fontist/ucode for the audit + UCD docs.
+
+== Installation
+...
+```
+
+## CHANGELOG entry
+
+Under the release that executes TODOs 17 + 18:
+
+```markdown
+## [Unreleased]
+
+### Breaking — audit + UCD migrated to ucode
+
+The following were removed from fontisan and are now provided by the
+`ucode` gem (https://github.com/fontist/ucode):
+
+- CLI: `fontisan audit`, `fontisan audit-compare`, `fontisan audit-library`,
+  `fontisan ucd`.
+- Modules: `Fontisan::Audit::*`, `Fontisan::Models::Audit::*`,
+  `Fontisan::Ucd::*`, `Fontisan::Models::Ucd::*`.
+- Formatters: `Fontisan::Formatters::AuditTextRenderer`,
+  `AuditDiffTextRenderer`, `LibrarySummaryTextRenderer`.
+
+### Migration
+
+Replace:
+
+  fontisan audit path/to/font.ttf
+
+with:
+
+  ucode audit font path/to/font.ttf
+
+Replace `Fontisan::Ucd::Database.open(version)` with
+`Ucode::Database.open(version)`. Full mapping table in ucode's
+`docs/guide/fontisan_migration.md`.
+
+The last fontisan release with audit + UCD code was X.Y.Z. The
+release before that (X.Y.Z-1) emitted deprecation warnings.
+```
+
+## Doc files to update in fontisan
+
+Audit the existing `fontisan/docs/`:
+
+- Any file mentioning `fontisan audit` → rewrite or delete.
+- Any file mentioning `fontisan ucd` → rewrite or delete.
+- Add `fontisan/docs/migrating_to_ucode.md` if a longer-form migration
+  guide is wanted (cross-link to ucode's
+  `docs/guide/fontisan_migration.md`).
+
+## Acceptance
+
+- fontisan's README has no `audit` or `ucd` command sections.
+- fontisan's CHANGELOG has clear breaking entries pointing at ucode.
+- fontisan's `docs/` has no stale audit/UCD references.
+- The compat shim (if introduced in Phase B) is removed in Phase D.
+- `fontisan.gemspec` does not list `ucode` as a runtime dep after
+  Phase D.
+- All fontisan specs pass; all fontisan rubocop checks pass.
+
+## References
+
+- Companion: `TODO.new/17-fontisan-cleanup-audit.md`
+- Companion: `TODO.new/18-fontisan-cleanup-ucd.md`
+- Migration runbook: `docs/FONTISAN_MIGRATION.md`
+- Migration guide: `docs/guide/fontisan_migration.md`