citation-work/workplans/CWORK-WP-0001-extract-review-workspace.md

---
id: CWORK-WP-0001
type: workplan
title: "Extract the existing review workspace slice into citation-work"
domain: infotech
repo: citation-work
status: finished
owner: codex
topic_slug: citation_evidence_mvp
created: "2026-06-21"
updated: "2026-07-09"
state_hub_workstream_id: "5978b563-16b7-41c2-8add-3f122dc3a61a"
---

# CWORK-WP-0001 — Extract the Existing Review Workspace Slice

## Goal

Turn `citation-work` from an INTENT-only repo into the standalone home of the
already-existing review workspace slice from `citation-evidence`, without
expanding scope beyond that current slice.

The implementation source of truth on 2026-07-08 is:

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

This workplan is intentionally Ralph-friendly: bounded, file-driven, and
self-closing once the extraction, cutover, docs, verification, and sync are
complete.

## Scope Locks

- **In scope:** repo scaffold, package/tooling setup, extraction of the current
  review workspace React surface, umbrella-app cutover, test porting, repo doc
  refresh, and closeout sync.
- **Out of scope for this workplan:** new product features not already present
  in the upstream slice, including collection search/filter, document review
  status UX, evidence status/tagging/filtering, and any binder-owned workflows.
- **Boundary rule:** `citation-work` may depend on `citation-engine`,
  `evidence-anchor`, and `evidence-source`, but not `evidence-binder`.
- **If extraction reveals missing engine contracts:** fix only the minimum
  import/integration issue needed to complete extraction, or register sibling
  follow-on work. Do not broaden this workplan into cross-repo feature design.

## Ralph Execution

Recommended invocation after review:

```text
/ralph-workplan workplans/CWORK-WP-0001-extract-review-workspace.md --max-iterations 12
```

Expected done condition:

- all tasks below are `done`,
- frontmatter status is updated to `finished`,
- State Hub task/workplan statuses and progress note are synced.

## Dependency Order

```text
T01 (repo scaffold + boundaries)
  └─ T02 (providers/hooks/barrel)
       ├─ T03 (collection pane + workspace shell)
       ├─ T04 (viewer + capture flow)
       └─ T05 (evidence sidebar + export flow)
            └─ T06 (umbrella cutover + test port)
                 └─ T07 (repo docs + deferred-gap registration)
                      └─ T08 (verification + sync + closeout)
```

## T01 — Bootstrap the repo scaffold and dependency boundaries

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

**Description**: Create the minimal standalone package/tooling baseline so this
repo can host extracted code instead of only intent docs.

**Implement**:

- Add repo-local package/tooling files adapted from `../citation-evidence/`:
  `package.json`, `tsconfig.json`, `vite.config.ts`, `vitest.config.ts`,
  `eslint.config.js`, and initial `src/` layout.
- Configure aliases and lint boundaries so `citation-work` may import only from
  `engine`, `anchor`, and `source`.
- Remove stale repo wording that still implies binder-owned form-binding layout
  belongs here.

**Acceptance criteria**:

- `pnpm lint`, `pnpm typecheck`, and `pnpm test` can run in this repo once the
  extracted files land.
- No local config permits imports from `binder`.
- README/AGENTS/SCOPE wording no longer contradicts the repo boundary.

**Deliverables**: runnable scaffolded repo with enforced dependency edges.

---

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

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

**Description**: Move the stateful review-workspace foundation out of the
umbrella repo first so the UI components have a stable local API.

**Source files**:

- `../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`

**Acceptance criteria**:

- `citation-work` exports the same provider/hook surface currently consumed by
  `citation-evidence/src/app/`.
- Session-scoped storage keys, pending-selection state, scroll-to-annotation
  behavior, and byte-store registry semantics remain unchanged.
- No extracted provider imports from umbrella-app files.

**Deliverables**: working local provider layer plus barrel exports.

---

## T03 — Extract the collection pane and workspace shell

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

**Description**: Move the left-pane and review-shell composition into
`citation-work`, including the upload seam decision.

**Source files**:

- `../citation-evidence/src/work/CollectionList.tsx`
- `../citation-evidence/src/app/ReviewLayout.tsx`
- `../citation-evidence/src/app/sessions/UploadDropzone.tsx` if kept as part of
  the review workspace surface

**Implement**:

- Make the three-pane review layout repo-owned.
- Decide whether `UploadDropzone` belongs in this repo or stays in the umbrella
  app as a narrow slot-based integration seam; document the decision in-code.
- Port `CollectionList.dom.test.tsx`.

**Acceptance criteria**:

- The extracted package can render the review shell with collection list and
  upload affordance without umbrella-local imports.
- The upload seam is explicit and stable.
- Collection list tests pass from this repo.

**Deliverables**: local review-shell component and collection-pane coverage.

---

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

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

**Description**: Move the center-pane review flow without changing the
viewer-adapter boundary.

**Source files**:

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

**Acceptance criteria**:

- `citation-work` talks to the viewer only through `anchor`/`source`
  contracts, not PDF.js internals.
- Pending selection, save/discard behavior, and active-evidence scroll behavior
  match the umbrella implementation.
- DOM coverage exists for capture create/save/discard flow and document-switch
  pending-selection reset.

**Deliverables**: extracted viewer/capture components plus local tests.

---

## T05 — Extract the evidence sidebar and export flow

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

**Description**: Move the right-pane evidence management UI and preserve the
current export/edit behaviors.

**Source files**:

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

**Acceptance criteria**:

- Document-order sorting, inline edit, pending-capture insertion, and
  Markdown/HTML clipboard export all behave as before.
- `Cmd/Ctrl+Shift+C` export still works for the active evidence item.
- `EvidenceSidebar.dom.test.tsx` is ported and extended to cover at least edit
  and activation behavior in addition to export.

**Deliverables**: extracted evidence sidebar flow plus local regression tests.

---

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

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

**Description**: Rewire `citation-evidence` so review mode consumes
`citation-work` as an extracted subsystem rather than a local `src/work/`
folder.

**Implement**:

- Update app-side imports in `../citation-evidence/src/app/App.tsx`,
  `../citation-evidence/src/app/ReviewLayout.tsx`,
  `../citation-evidence/src/app/forms/`, and
  `../citation-evidence/src/app/sessions/` as needed.
- Keep top-bar routing, empty-state session creation, and binder/forms
  composition in the umbrella repo.
- Port or update app-side tests affected by the import change.

**Acceptance criteria**:

- Review mode still supports session switching, PDF upload, collection list,
  viewer, evidence capture, and evidence export after the cutover.
- The umbrella repo no longer depends on a local `src/work/` implementation for
  review mode.

**Deliverables**: externalized package consumption from the umbrella app.

---

## T07 — Refresh repo docs and register deferred follow-on gaps

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

**Description**: Finish the repo transition from placeholder to extracted
package and record what remains intentionally out of scope for this slice.

**Implement**:

- Update `README.md`, `SCOPE.md`, and any local orientation docs to describe the
  extracted implementation instead of a future placeholder.
- Record deferred workspace gaps explicitly:
  collection search/filter, document review status UX, evidence
  status/tagging/filtering, and any other notable INTENT-vs-implementation gap.
- If helpful, name the next follow-on workplan slice, but do not expand this
  workplan to include it.

**Acceptance criteria**:

- A new contributor can tell from repo docs what code now lives here and what
  still remains for later work.
- Deferred items are written down clearly enough to seed a subsequent workplan
  without rediscovery.

**Deliverables**: accurate repo docs plus explicit deferred-gap list.

---

## T08 — Verify, sync, and close the extraction slice

```task
id: CWORK-WP-0001-T08
status: done
priority: high
depends_on: [T07]
state_hub_task_id: "c094f3ad-1793-4a61-b32f-2d8108f07e4b"
```

**Description**: Close the workplan cleanly so Ralph can retire with HEUREKA
and the State Hub read model matches the file.

**Acceptance criteria**:

- Local verification passes: `pnpm lint`, `pnpm typecheck`, and `pnpm test`.
- Workplan tasks marked `done` in the file are also marked `done` in State Hub.
- `fix-consistency` runs cleanly and updates `.custodian-brief.md` as needed.
- A progress note is posted summarizing what was extracted and what was deferred.
- Frontmatter status is updated from `ready`/`active` to `finished`.

**Deliverables**: passing extracted repo, synced hub state, and clean closeout.

## Deferred After This Workplan

These are intentionally not part of the Ralph loop for `CWORK-WP-0001`:

- collection search/filter UX,
- document review-status interactions,
- evidence-item status/tagging/filtering UX,
- any binder-integrated review-to-form workflows,
- any new viewer/document-format features not already in the current upstream
  `src/work/` slice.