coulomb/citation-work
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: extract review-workspace slice into @citation-evidence/work (CWORK-WP-0001)
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 3s
Details

Browse source 
Establishes citation-work as the standalone home of the review workspace,
migrated out of the citation-evidence umbrella app.

- Package/tooling scaffold: package.json, tsconfig, vite/vitest/eslint configs
  with eslint-plugin-boundaries enforcing engine/anchor/source-only imports
- Providers/hooks: EngineProvider, SessionProvider + use* hooks (T02)
- Panes: CollectionList, ViewerShell, EvidenceSidebar (T03/T04/T05)
- Capture/edit: InlineCaptureForm, EvidenceFormBody; UploadDropzone owned here
- ReviewShell: repo-owned three-pane layout with an upload slot seam
- Tests: CollectionList, InlineCaptureForm capture flow, EvidenceSidebar
  export/edit/activation (11 tests, all green)
- Anchor consumed as @citation-evidence/evidence-anchor package; @source kept
  on the umbrella facade for its local viewer-url policy
- Docs (README/SCOPE) refreshed; deferred gaps recorded

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-07-09 01:49:28 +02:00
parent c51ef94812
commit 0cd2ca5d04
30 changed files with 7958 additions and 342 deletions
Download patch file Download diff file Expand all files Collapse all files

341
workplans/CWORK-WP-0001-extract-review-workspace.md Normal file
View file

@ -0,0 +1,341 @@
---
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.

276
workplans/CWORK-WP-0001-intent-placeholder.md
View file

@ -1,276 +0,0 @@
---
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.