diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md index 80a6715..b1183a6 100644 --- a/.claude/rules/workplan-convention.md +++ b/.claude/rules/workplan-convention.md @@ -46,7 +46,7 @@ fix-consistency. Do not edit or rename it. **Workplan** is the fleet term — see `the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`. -**Workstream** is legacy only: some API routes (`/workstreams/`), params +**Workplan** is legacy only: some API routes (`/workstreams/`), params (`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new diff --git a/workplans/CWORK-WP-0001-intent-placeholder.md b/workplans/CWORK-WP-0001-intent-placeholder.md index 839db20..87c92f8 100644 --- a/workplans/CWORK-WP-0001-intent-placeholder.md +++ b/workplans/CWORK-WP-0001-intent-placeholder.md @@ -1,19 +1,276 @@ --- id: CWORK-WP-0001 type: workplan -title: "INTENT placeholder — await extraction from citation-evidence" +title: "Stand up citation-work and extract the review workspace from citation-evidence" domain: infotech repo: citation-work -status: backlog +status: ready owner: codex topic_slug: citation_evidence_mvp created: "2026-06-21" -updated: "2026-06-21" +updated: "2026-07-08" state_hub_workstream_id: "5978b563-16b7-41c2-8add-3f122dc3a61a" --- -# CWORK-WP-0001 — INTENT Placeholder +# CWORK-WP-0001 — Stand Up `citation-work` -Umbrella-first MVP: review workspace code will extract from `citation-evidence` -when the subsystem boundary stabilizes. This file satisfies ADR-001 workplan -structure until then. See `INTENT.md`. \ No newline at end of file +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.