coulomb/citation-work
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
citation-work/workplans/CWORK-WP-0001-intent-placeholder.md
tegwick c4b2c9499f
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 8s
Details
docs: workplan-first agent guidance prose (CUST-WP-0055 T04 batch 5)
2026-07-08 19:51:10 +02:00

9.5 KiB
Raw Blame History

id type title domain repo status owner topic_slug created updated state_hub_workstream_id
CWORK-WP-0001 workplan Stand up citation-work and extract the review workspace from citation-evidence infotech citation-work ready codex citation_evidence_mvp 2026-06-21 2026-07-08 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

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

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

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

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

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

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

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

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

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.