citation-evidence/history/2026-05-24-initial-assessment.md

# Initial Assessment — citation-evidence ecosystem

**Date:** 2026-05-24
**Author:** Claude (Opus 4.7), commissioned by Bernd
**Scope:** Review of `citation-evidence` umbrella PRD and Architecture overview, plus all five sister-repo `INTENT.md` files, for alignment, risk, and recommended approach.

---

## 1. Overall alignment across the six INTENT.md files

The vocabulary is impressively coherent: every repo speaks of
`Document → DocumentRepresentation → Annotation → Selector → EvidenceItem → EvidenceLink → CitationCard`.
Each `INTENT.md` follows the same Purpose / Scope / Out-of-Scope / Architectural Position / First-Useful-Version / Success Criteria shape.
Out-of-scope sections show the authors deliberately *pushing* responsibilities into other repos — a healthy signal.

The PRD and Architecture overview in `citation-evidence/wiki/` are also internally consistent: the PRD's functional requirements map cleanly to the architecture's data flows and to subsystem scopes.

But the documents were authored in quick succession (all on 2026-05-24, within ~30 minutes of each other based on file timestamps) and **never reconciled against each other**, which created the issues below.

## 2. What should be improved

### 2.1 Concrete ownership ambiguities to resolve in short ADRs

| Concept | Conflict |
|---|---|
| **`Selector` types** | `citation-engine` claims it as a "key concept owned"; `evidence-anchor`'s scope lists "selector type definitions". Likely fix: *interfaces* in engine, *creation/resolution/algorithms* in anchor. |
| **`EvidenceLink` / `EvidenceSet`** | Engine claims both as owned domain types; `evidence-binder` lists "evidence-to-target binding model" and "evidence sets" in scope. Same engine-defines-type / binder-owns-behavior split needed. |
| **Status enums** | Architecture's `EvidenceItem.status` is `candidate\|confirmed\|rejected\|needs-check`. `citation-work` adds `strong-support\|weak-support\|contradicts`. `evidence-binder` adds *target-specific* states (`conflicting-evidence`, `insufficient-evidence`, `verified`) plus extra relations (`context-for`, `derived-from`, `needs-check`). Three repos inventing overlapping enums. |
| **Viewer adapters** | Architecture diagram shows them as a separate box, no owner. Adapter methods (`load`, `createSelectorsFromSelection`, `resolveSelectors`, `scrollToResolvedTarget`, `renderHighlight`) straddle `evidence-source` and `evidence-anchor`. Pick one home (likely `evidence-anchor`, with `evidence-source` providing the representation). |
| **`CitationRecoveryAttempt`** | Type in engine, behavior in `evidence-source` — semantic ownership split that will rot. |
| **Document review status (FR-006)** | No repo claims it; `citation-work` hints "may later be moved into a shared model". |

### 2.2 Repository scaffolding gaps

- The umbrella architecture (§3.1) promises `apps/workspace-demo/`, `docs/decisions/`, `integration-tests/`, `docker-compose.yml` — none of this exists yet.
- All six READMEs are essentially empty (1 line). New contributors and agents won't know where to start.
- `citation-evidence` is **not registered in the state-hub**. For a project that splits across six repos, you lose central memory of decisions/dependencies/progress without it.

### 2.3 Architectural decisions still pending

ADR-001 through ADR-005 in the architecture doc are framed as "recommendations" rather than commitments. Each blocks code:

- React-first vs web-component-first (drives repo packaging)
- Local-first vs server-first storage (drives persistence interface shape)
- W3C internal model vs mapping (drives every type definition)
- `react-pdf-highlighter-plus` vs PDF.js direct (drives MVP timeline by weeks)
- Recovery scope local-only vs external

### 2.4 Missing cross-repo contract artefacts

There is no central dependency map. Each repo says "I expect to depend on X" but nothing names which repo *publishes* the shared types package(s). Pick monorepo (pnpm workspace) vs polyrepo with published `@citation-evidence/engine` npm packages before the first commit of code lands — switching later is painful.

## 3. Technical risks to inspect first

In rough order of "if this is broken, the architecture doesn't work":

1. **PDF canonical-text stability** — the entire selector/anchor model assumes a given PDF + extraction pipeline produces *the same* canonical text each time. PDF.js text extraction has known issues with multi-column layouts, custom-glyph fonts, ligatures, soft hyphens, and reading order. Build a corpus of 15-20 representative PDFs (governmental forms, two-column papers, scanned-then-OCR'd, German umlauts) and confirm round-trip selector resolution before committing to the model.

2. **`react-pdf-highlighter-plus` abstraction leakage** — this library is opinionated; wrapping it cleanly while keeping the engine viewer-independent is the central architectural test. Do a focused spike: load PDF → select → store selectors as JSON → reload page → resolve from JSON → highlight. If this leaks PDF.js types into the engine API, the boundary fails on day one.

3. **Canonical-text normalization is a silent migration** — every stored annotation's `TextQuoteSelector` / `TextPositionSelector` depends on the *exact* normalization rules used at creation time. Treat normalization as a versioned, deterministic function from day one. If you change Unicode normalization or whitespace handling later, every stored annotation breaks silently.

4. **Visual guide overlay coupling** — `evidence-binder` owns the visual-guide *model*, but rendering needs DOM rects from three sources: the form (binder's UI?), the evidence sidebar (`citation-work`), and the document highlight (viewer adapter). Three subsystems contributing rects to one overlay is the highest-coupling part of the system. Define an explicit *rect registry* contract before any of them ships UI.

5. **CSS Custom Highlight API support** — architecture mentions it for HTML/Markdown with fallback. Browser support is uneven; the fallback (usually DOM range-based span wrapping) is what will actually run on most users' machines. Verify the fallback path is acceptable, not the optimistic primary.

6. **W3C Web Annotation mapping is not free** — JSON-LD selectors can express things your internal model can't (and vice versa). Round-tripping is a research task, not a one-day mapping. Decide whether mapping is "lossy but useful" or "MUST round-trip" before stabilizing types.

7. **Multi-repo dependency cycle risk** — engine ↔ anchor (`Selector` ownership), engine ↔ source (`RecoveryAttempt`), engine ↔ binder (`Link`/`Set`) all currently look bidirectional in the INTENT files. Without a strict "types-only flow downward, behavior flows upward" rule, you will hit `npm install` cycles.

## 4. Rough approach (original phased plan)

**Phase 0 — Foundations (1-2 weeks, no production code)**
- Register `citation-evidence` as a state-hub domain + register all six repos
- Write 5-7 micro-ADRs in `citation-evidence/docs/decisions/` resolving the ownership ambiguities above
- Pick monorepo-vs-polyrepo and pin Node/TS toolchain
- Assemble a 15-20 PDF test corpus and check it into a fixtures location
- Write a real README for each repo pointing at INTENT + architecture

**Phase 1 — Vertical slice on the easiest format (4-6 weeks)**
- Engine: TS types + in-memory repos only
- Anchor: text-quote + text-position selectors, fuzzy match deferred
- Source: PDF text extraction + fingerprint only
- Work: one-document UI, sidebar, create annotation, click-to-reopen
- Umbrella: wire it into a reference app
- Goal: prove viewer-independence on PDFs end-to-end. No forms, no recovery, no Markdown.

**Phase 2 — Evidence binding & form mode (4 weeks)**
- Binder + visual-guide rect registry
- One form-schema example with side-by-side viewer
- This is where the active-state coordination claim gets stress-tested

**Phase 3 — Format expansion (4 weeks)**
- HTML adapter (sanitization + DOM range selectors)
- Markdown adapter
- Confirms the format-neutral claim

**Phase 4 — Local citation recovery (4 weeks)**
- Local-library search, exact + fuzzy quote match, confirmation UI
- Defer external source lookup until local pipeline is reliable

## 5. Pivot — umbrella-first MVP (decided 2026-05-24)

The user has chosen to **build the MVP entirely inside `citation-evidence`** before segmenting code into the sister repos. The reasoning: get the product working end-to-end with minimal coordination cost, then extract subsystems once the contracts have been validated by actual use.

This means:

- All MVP source code lives under `citation-evidence/` (likely `src/` partitioned by future-repo names: `engine/`, `anchor/`, `source/`, `work/`, `binder/`).
- The five sister repos remain as INTENT-only placeholders during MVP — they document the intended boundaries, but code will move in only when a subsystem's contract has stabilized.
- Interface design is explicitly deferred. Phase-0 ADRs become Phase-N extractions, informed by real friction points.
- Shared contracts live in `citation-evidence/wiki/SharedContracts.md` and `citation-evidence/wiki/DependencyMap.md`.

This trade-off accepts more rework later (when subsystems extract) in exchange for faster MVP velocity now and better-informed boundaries when extraction happens.