citation-work/INTENT.md

# INTENT

## Purpose

This repository exists to provide the document review workspace for the **citation-evidence** ecosystem.

**citation-work** enables users to review collections of documents, mark relevant passages, add commentary, and create reusable evidence items that can later support form fields, claims, requirements, decisions, reports, or web publications.

It is the human-facing workbench for turning document reading into structured evidence.

---

## Primary Utility

The repository provides the review and annotation user experience for citation-evidence.

It should make it easy to:

- open and navigate document collections,
- review documents efficiently,
- select relevant passages,
- create annotations,
- add commentary,
- convert annotations into evidence items,
- browse collected evidence,
- navigate from evidence items back to source context,
- prepare evidence for later binding, export, or citation rendering.

This repository turns the core model from **citation-engine** and the anchoring capabilities from **evidence-anchor** into a practical working environment.

---

## Intended Users

Primary users are people who need to read documents and collect useful, source-backed evidence.

They include:

- researchers and analysts reviewing document sets,
- consultants and knowledge workers preparing reports,
- compliance, audit, procurement, and legal-adjacent workers collecting source support,
- product and requirements workers extracting evidence from source material,
- form workers preparing evidence before structured data entry,
- developers and coding agents building review workflows on top of citation-evidence.

End users should experience this repository as the place where document review happens.

---

## Strategic Role

The strategic role of **citation-work** is to provide the first usable surface of the citation-evidence system.

It should prove that the system can support a complete evidence capture loop:

```text
Document Collection
  → Document Viewer
  → Text Selection
  → Annotation
  → Commentary
  → Evidence Item
  → Evidence Sidebar
  → Reopen Source Context
````

The repository should focus on workflow quality: reducing friction between reading, noticing, marking, commenting, and later reusing evidence.

---

## Core Concept

The central concept of **citation-work** is the **review workspace**.

A review workspace combines:

* a document collection,
* a document viewer,
* an annotation creation workflow,
* an evidence sidebar,
* review status,
* search and filtering,
* navigation back to source context.

The workspace should help users move from unstructured reading to structured evidence without interrupting concentration.

---

## Scope

This repository should own:

* document collection review UI,
* document list and navigation UI,
* review queue behavior,
* document viewer shell composition,
* annotation toolbar and selection UX,
* evidence sidebar,
* evidence item browsing,
* review status interactions,
* evidence status interactions,
* tagging and filtering UI,
* navigation from evidence item to source context,
* review-oriented keyboard shortcuts,
* user workflows for collecting evidence before later binding or export.

It should consume domain services and types from **citation-engine** and anchoring/viewer contracts from **evidence-anchor**.

---

## Out of Scope

This repository should not own the lower-level or broader system concerns.

Specifically, it should not own:

* the canonical domain model,
* persistence contracts,
* low-level selector resolution algorithms,
* PDF text extraction internals,
* Markdown or HTML ingestion pipelines,
* external source discovery,
* citation recovery logic,
* form-field binding semantics,
* visual guide overlay logic for evidence-backed forms,
* citation card rendering internals,
* product-level deployment and integration shell.

Those responsibilities belong to the appropriate subsystem repositories.

---

## Architectural Position

```text
citation-evidence
  integrated product shell and reference application

citation-work
  review workspace, annotation UX, evidence sidebar

citation-engine
  domain model, services, persistence contracts, citation rendering

evidence-anchor
  selector creation, selector resolution, highlighting contracts

evidence-source
  document ingestion, representations, source recovery

evidence-binder
  evidence-to-field / claim / requirement binding
```

**citation-work** should act as a user-facing application layer that composes capabilities from the core subsystems.

It should not redefine their domain concepts.

---

## Primary Workflows

### 1. Open Review Collection

A user opens or creates a document collection and sees the available documents, review states, and collected evidence.

```text
Open Collection
  → List Documents
  → Show Review Status
  → Select Document
  → Display Document in Viewer
```

### 2. Create Evidence from Selection

A user selects text in a document, creates an annotation, adds commentary, and stores it as an evidence item.

```text
Select Text
  → Capture Selection
  → Create Selectors
  → Create Annotation
  → Add Commentary
  → Create Evidence Item
  → Show in Evidence Sidebar
```

### 3. Review Evidence

A user browses collected evidence, filters it, changes status, and jumps back to source context.

```text
Browse Evidence
  → Filter by Document / Tag / Status
  → Select Evidence Item
  → Resolve Annotation
  → Scroll Document to Source Context
  → Highlight Passage
```

### 4. Prepare Evidence for Later Use

A user organizes evidence so that it can later be bound to fields, claims, requirements, or exported as citations.

```text
Evidence Item
  → Add Tags
  → Set Status
  → Refine Commentary
  → Mark as Candidate / Confirmed / Needs Check
```

---

## Initial Review States

Documents should initially support review states such as:

```text
unreviewed
in-review
marked
relevant
rejected
needs-follow-up
cited
verified
```

These states may later be refined or moved into a shared model if they become central across subsystems.

---

## Initial Evidence States

Evidence items shown in the review workspace should initially support states such as:

```text
candidate
confirmed
rejected
needs-check
strong-support
weak-support
contradicts
```

The canonical state model should remain aligned with **citation-engine**.

---

## Initial UI Areas

The first review workspace should likely contain:

```text
Workspace Header
  collection name, document count, review progress

Document Navigation
  document list, filters, status indicators

Document Viewer Shell
  PDF / Markdown / HTML viewer integration

Annotation Toolbar
  create annotation, add commentary, tag, save

Evidence Sidebar
  collected evidence, comments, tags, status, source jump

Status / Filter Controls
  review status, evidence status, tags, search
```

Reference layout:

```text
┌─────────────────────────────────────────────────────────────┐
│ Workspace Header                                             │
├───────────────┬───────────────────────────────┬─────────────┤
│ Document List  │ Document Viewer                │ Evidence    │
│ / Filters      │                               │ Sidebar     │
└───────────────┴───────────────────────────────┴─────────────┘
```

---

## Design Principles

### Review Flow First

The interface should minimize friction between reading, marking, commenting, and moving on.

### Evidence Visibility

Collected evidence should remain visible enough that users understand what has already been captured.

### Source Context Is Always Recoverable

Every evidence item should provide a direct path back to the source passage.

### Format Neutrality

The review experience should work across PDFs, Markdown, HTML, and future document formats through viewer adapters.

### Domain Alignment

The repository should use concepts from **citation-engine** rather than inventing parallel local models.

### Anchoring Delegation

Selector creation, resolution, and re-anchoring should be delegated to **evidence-anchor**.

### Progressive Complexity

The first version should support a simple review loop before adding advanced search, collaboration, or automated suggestions.

### Agent Compatibility

The workflow should be explicit enough that agentic assistants can help find candidate evidence, summarize marked passages, propose tags, or identify missing evidence.

---

## Expected Dependencies

This repository is expected to depend on:

```text
citation-engine
  domain types, services, citation rendering contracts

evidence-anchor
  selection capture contracts, selector creation, annotation resolution

evidence-source
  document representations and viewer-ready sources

possibly citation-evidence
  for integration shell during reference app development
```

It should avoid direct dependency on **evidence-binder** unless building a review-to-binding bridge. Binding-specific behavior should remain outside the core review workspace.

---

## First Useful Version

A first useful version of **citation-work** should provide:

* a simple document collection view,
* a PDF document viewer shell,
* text selection capture through an adapter,
* annotation creation flow,
* commentary input,
* evidence item creation through **citation-engine**,
* evidence sidebar,
* click evidence item to reopen highlighted source context,
* basic document and evidence status display.

This version should prove that a user can review a document and produce reusable evidence.

---

## Success Criteria

The repository is successful when a user can efficiently perform the basic evidence capture loop:

1. open a document collection,
2. select a document,
3. read the document,
4. mark a relevant passage,
5. add commentary,
6. save it as evidence,
7. see it in the evidence sidebar,
8. return to the cited passage by clicking the evidence item.

A developer or coding agent should also be able to understand which parts of the workflow belong here and which belong to the underlying subsystems.

---

## Repository Character

This repository should be:

* user-workflow-oriented,
* interface-focused,
* thin over the domain engine,
* explicit about review concepts,
* careful not to absorb core model responsibilities,
* friendly to fast MVP iteration,
* suitable for later integration into the umbrella product shell.

---

## MVP Coordination — Code Lives Upstream

During the umbrella-first MVP phase (decided 2026-05-24), **the source code
for this subsystem does not live in this repository yet**. It lives in the
umbrella repo at `citation-evidence/src/work/`.

This INTENT.md documents the *intended* responsibilities and boundaries.
When the review workspace UX has stabilized through actual MVP use, the
corresponding code extracts into this repository.

**Shared contracts** (Document.reviewStatus enum, EvidenceItem.status enum,
viewer adapter contract, allowed dependency edges) are maintained in the
umbrella repo:

* `citation-evidence/wiki/SharedContracts.md`
* `citation-evidence/wiki/DependencyMap.md`
* `citation-evidence/docs/decisions/` (ADRs)

This subsystem's eventual code must not contradict those documents. The
extra evidence states (`strong-support`, `weak-support`, `contradicts`)
mentioned in the original INTENT now live on `EvidenceLink.relation`, not on
the item itself — see `SharedContracts.md` §2.5.

Under the dependency map, **`citation-work` may depend on `citation-engine`,
`evidence-anchor`, and `evidence-source`** — but NOT on `evidence-binder`.
The review workspace must function without form-binding logic. A separate
"evidence-backed form" application composes `citation-work` + `evidence-binder`.

---

## Guiding Statement

**citation-work exists to turn document review into reusable evidence capture.**