feat(annotator): Antecedent Annotator — full-stack workbench for the labeled Id./supra corpus

[medelman17]

What this is

A local, dockerized workbench where legal experts record what each "Id."/"supra" back-reference actually points to (its antecedent). The eyecite-ts engine pre-computes each back-reference's best guess + ranked candidates into Postgres; the human confirms the guess with one keystroke or corrects it. The output is a clean, exportable gold corpus of Id./supra → antecedent labels.

Why it matters: that labeled corpus is the missing ingredient gating the resolver research — measuring how often the engine is wrong, training a learned ranker, and calibrating abstention. None existed; this is the tool that produces it.

Before / Now

• Before: eyecite-ts extracts and resolves citations, but there was no way to capture human ground-truth on short-form antecedents.
• Now: sample/seed real opinions → engine prefill → Postgres → a keyboard-first React workbench (Review · Adjudicate · Corpus) → exportable gold JSONL. The whole stack comes up with docker compose up.

What's included

• Backend (apps/annotator, Hono + postgres.js, 4 migrations): read API (document contract), label-write (POST /labels, next-unlabeled, resume, batches, annotators), adjudication queue + gold decisions, Cohen's κ inter-annotator agreement, and gold NDJSON export. A pure buildDocumentPayload maps extractCitations(text, { resolve: true }) → the UI contract (engine guess, ranked candidates, confidence, warnings, isBuriedAside via public fullSpan containment).
• Corpus: replica ingestion (pnpm ingest, over-sampling parenthetical-dense hard cases) + a seed of four canonical hard-case opinions (Hogue/Corsello buried-paren, same-name Smith, supra, prose-introduced Yellen chain, string-cite abstain, nested Bryant/Davis) run through the real engine.
• Frontend (apps/annotator/web, Vite + React + TS): the three surfaces from the approved Claude-design handoff, ported faithfully (dark theme, Spectral/IBM Plex, keyboard-first), wired to the live API and a11y-hardened (focus-visible, keyboard-operable controls, dialog semantics, live region, contrast, reduced-motion, 24px targets).
• Docker: postgres + api + web via compose; nginx proxies /api.

The eyecite-ts core (src/) is untouched — the annotator is a private workspace app importing the published surface, so there's no changeset (nothing to release).

Verification (what was actually run)

• Backend: 83 vitest integration tests pass against Postgres (TDD throughout; files run serially for determinism).
• Frontend: tsc clean + vite build clean.
• pnpm lint (CI gate) exits 0; git diff main..HEAD -- src/ is empty (core unchanged).
• Full stack: docker compose up --build → /healthz ok, web SPA serves, /api/healthz through the nginx proxy ok, seeded batch-042 (κ≈0.52) flows web→nginx→api→db.

Notable finding

Seeding through the real engine surfaced the real-vs-assumed divergences the corpus exists to quantify: the engine resolves an extra shortFormCase back-reference in one opinion and does not resolve a statute-section § …, supra in another — a candidate resolveSupra enhancement. Captured (with the deferred frontend decomposition + residual a11y items) in docs/superpowers/plans/2026-06-03-antecedent-annotator-followups.md.

Test plan

• docker compose -f apps/annotator/docker-compose.yml up --build, then open http://localhost:8080
• docker compose -f apps/annotator/docker-compose.yml exec api pnpm seed; verify Review / Adjudicate / Corpus load real data
• (optional, with the db up) cd apps/annotator && pnpm exec vitest run

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.51%. Comparing base (34133d0) to head (e14a95e).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #829   +/-   ##
=======================================
  Coverage   98.51%   98.51%           
=======================================
  Files         136      136           
  Lines        6243     6243           
  Branches     2066     2066           
=======================================
  Hits         6150     6150           
  Misses         93       93           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.