docs: workplan-first agent guidance prose (CUST-WP-0055 T04 batch 5)

.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

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