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

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
CWORK-WP-0001	workplan	Extract the existing review workspace slice into citation-work	infotech	citation-work	finished	codex	citation_evidence_mvp	2026-06-21	2026-07-09	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:

/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

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

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

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

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

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

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

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

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

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.