---
id: CWORK-WP-0001
type: workplan
title: "Stand up citation-work and extract the review workspace from citation-evidence"
domain: infotech
repo: citation-work
status: ready
owner: codex
topic_slug: citation_evidence_mvp
created: "2026-06-21"
updated: "2026-07-08"
state_hub_workstream_id: "5978b563-16b7-41c2-8add-3f122dc3a61a"
---

# CWORK-WP-0001 — Stand Up `citation-work`

Repo review on 2026-07-08 found that `citation-work` is still INTENT-only.
The implementation source of truth currently lives upstream in:

- `../citation-evidence/src/work/`
- `../citation-evidence/src/app/ReviewLayout.tsx`
- `../citation-evidence/src/app/sessions/UploadDropzone.tsx`

That upstream slice already covers:

- session-scoped engine/session providers and barrel exports,
- collection list and review-layout composition,
- PDF viewer shell and selection capture,
- evidence sidebar, inline edit, and Markdown/HTML export,
- DOM tests for collection and evidence-sidebar flows.

It does **not** yet cover several workflows promised by `INTENT.md` and the
umbrella PRD: collection search/filter, document review status UX, evidence
status/tags/filtering, and repo-local packaging/tooling/docs. This workplan
replaces the old placeholder with the concrete extraction and gap-closure work.

If T07/T08 reveal missing shared types or engine mutators, create sibling work
in `citation-engine` rather than storing shadow state locally in `citation-work`.

## Dependency Order

```text
T01 (repo bootstrap + boundary docs)
  └─ T02 (providers + public API)
       ├─ T03 (workspace shell, collection list, upload seam)
       └─ T04 (viewer shell + capture flow)
            └─ T05 (evidence sidebar + export flow)
                 └─ T06 (umbrella app cutover + test port)
                      ├─ T07 (collection search/filter + document review status)
                      └─ T08 (evidence status/tags/filtering + closeout)
```

## T01 — Bootstrap the repo as a real package

```task
id: CWORK-WP-0001-T01
status: todo
priority: high
state_hub_task_id: "a4fc2589-c922-4740-8817-8098698facbc"
```

Create the standalone repo scaffold that the placeholder never had.

- Add the package/tooling baseline adapted from `../citation-evidence/`:
  `package.json`, `tsconfig.json`, `vite.config.ts`, `vitest.config.ts`,
  `eslint.config.js`, and `src/`.
- Establish the allowed dependency edges only: `citation-engine`,
  `evidence-anchor`, and `evidence-source`; enforce the "`citation-work` may
  not import from `binder`" boundary with lint/config.
- Update repo docs so they match the actual boundary. In particular, remove the
  stale README wording that implies a form-binding layout owned here even though
  binder is explicitly out of scope.

Acceptance: the repo can run `pnpm lint`, `pnpm typecheck`, and `pnpm test`
locally before any large component move lands.

---

## T02 — Extract providers, hooks, and the public barrel

```task
id: CWORK-WP-0001-T02
status: todo
priority: high
depends_on: [T01]
state_hub_task_id: "d2e4c9da-915c-49ea-af7d-d927d935b13a"
```

Move the stateful review-workspace foundation out of the umbrella app:

- `../citation-evidence/src/work/index.ts`
- `../citation-evidence/src/work/EngineContext.tsx`
- `../citation-evidence/src/work/SessionContext.tsx`
- `../citation-evidence/src/work/SessionContextInternal.ts`
- `../citation-evidence/src/work/useDebugFlags.ts`

Preserve the current session-scoped localStorage keys, byte-store registry,
engine-event hooks, pending-selection state, and scroll-to-annotation contract.
Audit the barrel against current consumers in `citation-evidence/src/app/` so
the exported API is complete before deeper UI extraction starts.

Acceptance: the umbrella app can import the current provider/hook surface from
the new repo without adding any `app/` or `binder/` dependency back-edges.

---

## T03 — Extract the review workspace shell and collection pane

```task
id: CWORK-WP-0001-T03
status: todo
priority: high
depends_on: [T02]
state_hub_task_id: "58e5be13-08e2-4cd9-a348-26abe0f717d9"
```

Move the collection-side review UI into this repo:

- `../citation-evidence/src/work/CollectionList.tsx`
- `../citation-evidence/src/app/ReviewLayout.tsx` or an equivalent
  repo-owned `ReviewWorkspace` composition component

Also settle the upload seam. `UploadDropzone.tsx` currently lives under
`citation-evidence/src/app/sessions/` but only depends on `source/` plus work
hooks. Move it here unless a clear app-only reason is documented; if it stays in
the umbrella app, freeze the slot contract explicitly in docs/tests.

Port `CollectionList.dom.test.tsx` and add a workspace-shell smoke test so the
three-pane layout remains repo-owned rather than app-owned glue.

Acceptance: `citation-work` can render the review shell and document list on
its own, with session title and upload affordance supplied through a stable API.

---

## T04 — Extract the viewer shell and selection-capture flow

```task
id: CWORK-WP-0001-T04
status: todo
priority: high
depends_on: [T02]
state_hub_task_id: "048efc6c-b744-4b68-8073-7bcfcfc0fc91"
```

Move the central document-review flow:

- `../citation-evidence/src/work/ViewerShell.tsx`
- `../citation-evidence/src/work/InlineCaptureForm.tsx`
- `../citation-evidence/src/work/EvidenceFormBody.tsx`

Keep the current adapter boundary intact: `citation-work` should talk to the
viewer through `@anchor`/`@source` contracts, not through PDF.js internals.
Preserve the pending-selection flow, active-evidence scroll behavior, and debug
flag hooks.

Add DOM coverage for:

- selection creates pending capture state,
- discard clears pending state,
- save creates annotation + evidence and clears the form,
- switching documents clears stale pending selection.

Acceptance: text selection in the extracted workspace still results in a saved
annotation/evidence pair without any direct dependency on umbrella-app code.

---

## T05 — Extract the evidence sidebar and export flow

```task
id: CWORK-WP-0001-T05
status: todo
priority: high
depends_on: [T04]
state_hub_task_id: "10bff27a-5c84-46e5-8e5b-dc5bea6d24ae"
```

Move the evidence-management UI:

- `../citation-evidence/src/work/EvidenceSidebar.tsx`
- `../citation-evidence/src/work/useExportEvidence.ts`

Preserve the existing behaviors:

- document-order sorting by selector position,
- inline quote/commentary edit,
- insertion of the pending capture form in document order,
- Markdown/HTML clipboard export,
- `Cmd/Ctrl+Shift+C` export for the active evidence item.

Port `EvidenceSidebar.dom.test.tsx` and extend it beyond export coverage to
exercise edit/save, activation-scroll, and capture-form ordering.

Acceptance: the extracted sidebar can activate, edit, and export evidence items
without importing from `binder` or umbrella-app helpers.

---

## T06 — Cut the umbrella app over to the extracted package

```task
id: CWORK-WP-0001-T06
status: todo
priority: high
depends_on: [T03, T05]
state_hub_task_id: "da66f601-0467-41dd-9a64-943b54f0a232"
```

Rewire `citation-evidence` so it consumes `citation-work` as an external
subsystem rather than the local `src/work/` folder.

- Update the umbrella app imports in `src/app/App.tsx`, `src/app/forms/`,
  `src/app/sessions/`, and related tests to target the extracted package.
- Keep app-only concerns in the umbrella repo: top-bar routing, session menu,
  empty-state creation flow, and binder/forms composition.
- Verify that review mode still supports session switching, PDF upload, review
  layout rendering, and evidence capture after the cutover.

Acceptance: the umbrella app no longer relies on a local `src/work/` tree for
review mode, and review-mode tests still pass from the app side.

---

## T07 — Add collection search/filter and document review-status UX

```task
id: CWORK-WP-0001-T07
status: todo
priority: medium
depends_on: [T06]
state_hub_task_id: "87211f5e-2e72-46ad-9f02-9e13ecbe9aa2"
```

Close the first gap between `INTENT.md` and the current upstream slice:

- support searching/filtering documents within the collection view,
- surface and persist `Document.reviewStatus` using the canonical values from
  `../citation-evidence/wiki/SharedContracts.md`,
- show enough status information in the collection pane to drive a real review
  queue instead of a bare file list.

If the current engine API cannot store/update `reviewStatus`, track that as a
small sibling prerequisite in `citation-engine` rather than inventing local
component state here.

Acceptance: a reviewer can narrow the collection, mark document review state,
reload, and see the same state restored through the normal engine/session path.

---

## T08 — Add evidence status, tags, filters, and repo closeout

```task
id: CWORK-WP-0001-T08
status: todo
priority: medium
depends_on: [T06]
state_hub_task_id: "c094f3ad-1793-4a61-b32f-2d8108f07e4b"
```

Close the remaining MVP gaps for the review workspace and then retire the
"intent-only" posture of this repo.

- Add evidence-item status editing using the canonical `EvidenceItem.status`
  values (`candidate`, `confirmed`, `rejected`, `needs-check`).
- Add evidence tags plus sidebar filtering by status/tag, matching the
  organizing workflows described in `INTENT.md`.
- Update `SCOPE.md`, README, and any repo-local orientation docs so they
  describe the extracted implementation rather than a future placeholder.
- Finish with full verification (`lint`, `typecheck`, `test`) and update this
  workplan from `ready` to `active`/`finished` as implementation actually moves.

Acceptance: `citation-work` is no longer just a placeholder repo; it owns the
review workspace package, its organizing UX, and its documentation with passing
local verification.