docs: v1.0.0 design — glossary, ADRs 0001-0006, public interface spec

[medelman17]

What this is

The complete v1.0.0 design package, produced through an architecture review, a four-way design-it-twice on the public interface, and a fork-by-fork grilling of every load-bearing decision. Docs only — no source changes, no changeset.

Contents

• CONTEXT.md — canonical v1 vocabulary (citation document, family/kind, edge, group, antecedent, footnote zone, confidence level, reason code, lint finding, canonical rendering)
• docs/v1-spec.md — the full public interface contract:
  • Pure-JSON citation document IR: 4 families × fine kinds, document-level edges/groups, content-hashed branded ids, textHash, schemaVersion
  • Two-function surface (extract, annotate) + pure helpers + optional CitationView; resolution always-on; footnotes on with one escape hatch
  • Categorical confidence { level, reasons } — no numeric score (prior art: the stalled feat!: confidence-scoring overhaul Phase 1-2 (structured Confidence type + scorer migration) #486/feat: structured confidence scoring (Phases 1-2) + README overhaul #487 overhaul and five miscalibration incidents)
  • format() (Bluebook rendering, the IR's inverse), lint() (R4.1 and friends as a pure IR consumer), published JSON Schema artifact, eyecite CLI
  • Three verification nets for the rewrite: regenerated corpus parity, the round-trip law over a generative corpus, schema validation
  • 0.x → v1 migration map, semver rules, deferred extension-layer blueprint
• docs/adr/0001–0006 — no plugin layer in v1; textHash-not-text; edges-canonical relations; per-text content-hashed ids; categorical confidence; format/lint IR-sufficiency commitment

Related

• feat(annotator): Antecedent Annotator — full-stack workbench for the labeled Id./supra corpus #829 is scoped in as v1 measurement infrastructure (gold Id./supra labels = the resolver rewrite's accuracy scoreboard) and was brought current with main
• Closes the design phase; implementation sequencing is the next step

🤖 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 (2ebfabd).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #898   +/-   ##
=======================================
  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.