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/ESRC-WP-0001-bootstrap-standalone-source-repo.md

@@ -0,0 +1,251 @@
+---
+id: ESRC-WP-0001
+type: workplan
+title: "Bootstrap standalone source repo from citation-evidence PDF slice"
+domain: infotech
+repo: evidence-source
+status: ready
+owner: codex
+topic_slug: citation_evidence_mvp
+created: "2026-06-21"
+updated: "2026-07-08"
+spec_refs:
+  - INTENT.md
+  - README.md
+  - ../citation-evidence/src/source/README.md
+  - ../citation-evidence/workplans/CE-WP-0002-pdf-review-slice.md
+  - ../citation-evidence/wiki/ArchitectureOverview.md
+  - ../citation-engine/README.md
+state_hub_workstream_id: "64771b5d-4b83-4848-a562-4b00aad017b2"
+---
+
+# ESRC-WP-0001 — Bootstrap Standalone Source Repo
+
+This repo is no longer blocked on pure intent. The upstream umbrella repo
+already contains a small but real `src/source/` slice: PDF ingest,
+fingerprinting, canonical-text extraction, browser upload helpers, and a
+source-to-anchor round-trip integration test.
+
+What is missing here is the standalone package/tooling, a clean extraction
+boundary, and the downstream wire-up so `citation-evidence` consumes
+`evidence-source` instead of its local `src/source/` copy.
+
+This workplan extracts the current PDF slice first. It does not try to ship
+Markdown/HTML representations, richer metadata extraction, or citation
+recovery in the same pass; those become follow-on workplans once the PDF
+boundary is stable.
+
+## Reviewed Repo State
+
+- `evidence-source` currently contains intent/docs/workplans only. There is no
+  package manifest, source tree, test harness, or fixture corpus here yet.
+- `../citation-evidence/src/source/` already implements:
+  `ingestPdf`, `extractPdf`, `fingerprintBytes`, `createPdfByteStore`,
+  `ingestPdfFromFile`, and `resolvePdfViewerUrl`.
+- `../citation-evidence/tests/integration/anchor-source-roundtrip.test.ts`
+  already covers the source-to-anchor contract and should remain an umbrella
+  integration test rather than becoming a private test in this repo.
+- `../citation-engine` already exposes the shared contracts this repo should
+  consume via `@citation-evidence/engine` and `@citation-evidence/engine/shared`.
+
+## Dependency Order
+
+```text
+T01 extraction boundary and import plan
+  -> T02 standalone package/tooling scaffold
+  -> T03 headless PDF ingest extraction
+  -> T04 browser/session helper placement
+  -> T05 subsystem test coverage and fixture ownership
+  -> T06 downstream citation-evidence wire-up
+  -> T07 repo docs, registry, and follow-on workplans
+```
+
+## T01 — Lock the Extraction Boundary
+
+```task
+id: ESRC-WP-0001-T01
+status: todo
+priority: high
+```
+
+Turn the current umbrella `src/source/` slice into an explicit extraction map.
+
+Decide and document:
+
+- which files move into `evidence-source` immediately,
+- which files stay in `citation-evidence` because they are app/session/viewer
+  concerns,
+- which contracts must come from `@citation-evidence/engine/shared`,
+- which cross-subsystem tests stay upstream in the umbrella repo.
+
+Minimum outcome:
+
+- `pdf/ingest.ts`, `pdf/extract.ts`, and `pdf/fingerprint.ts` are confirmed as
+  in-scope for this repo,
+- `pdf/byte-store.ts`, `pdf/upload.ts`, and `pdf/viewer-url.ts` are explicitly
+  classified instead of carried over by default,
+- the extraction note points at the exact upstream files being replaced.
+
+Acceptance: there is a short boundary note or ADR in this repo and no part of
+the extraction relies on copying `citation-engine` shared types locally.
+
+## T02 — Add Standalone Package and Tooling
+
+```task
+id: ESRC-WP-0001-T02
+status: todo
+priority: high
+```
+
+Create the minimal standalone development surface for this repo.
+
+Add:
+
+- `package.json` with sibling-checkout dependency on
+  `@citation-evidence/engine` via `link:../citation-engine`,
+- TypeScript, Vitest, and ESLint configuration,
+- a `src/` tree for extracted code,
+- a `tests/` tree and fixture location strategy,
+- documented repo-local commands for `test`, `typecheck`, and `lint`.
+
+Keep the first extraction small: one package is enough until multiple formats
+or distribution constraints justify a more granular package layout.
+
+Acceptance: this repo can install dependencies and run meaningful test,
+typecheck, and lint commands without depending on `citation-evidence` as its
+runtime host.
+
+## T03 — Extract the Headless PDF Ingest Core
+
+```task
+id: ESRC-WP-0001-T03
+status: todo
+priority: high
+```
+
+Port the current headless PDF ingest pipeline from
+`../citation-evidence/src/source/pdf/` into this repo.
+
+Scope:
+
+- `ingestPdf`
+- `extractPdf`
+- `fingerprintBytes`
+
+Requirements:
+
+- preserve the current PDF behavior from `CE-WP-0002-T03`,
+- import `Document`, `DocumentRepresentation`, `newId`, and `normalize` from
+  `@citation-evidence/engine/shared`,
+- keep ingest pure over bytes and extraction results,
+- do not mix persistence, viewer state, or React concerns into the core.
+
+Acceptance: a consumer can pass PDF bytes to this repo and receive a valid
+`{ document, representation }` pair using only engine-owned contracts.
+
+## T04 — Place the Browser and Session Helpers Deliberately
+
+```task
+id: ESRC-WP-0001-T04
+status: todo
+priority: high
+```
+
+The upstream source slice currently includes browser-facing helpers for local
+uploads and `blob:` URL management. Those are useful, but they are not the same
+thing as headless ingest.
+
+Decide one of two outcomes:
+
+1. Keep these helpers in `evidence-source`, but isolate them clearly under a
+   browser-focused surface with documentation that distinguishes them from the
+   headless core.
+2. Leave them in `citation-evidence` / `citation-work` because they are viewer
+   or session infrastructure, and remove them from this repo's initial scope.
+
+Modules to classify:
+
+- `pdf/byte-store.ts`
+- `pdf/upload.ts`
+- `pdf/viewer-url.ts`
+
+Acceptance: there is no ambiguous mix of headless ingest code and
+browser/session-only behavior after extraction.
+
+## T05 — Rebuild Subsystem Test Coverage Here
+
+```task
+id: ESRC-WP-0001-T05
+status: todo
+priority: high
+```
+
+Re-establish the source repo's own verification surface.
+
+Port or recreate:
+
+- fixture-driven ingest contract tests,
+- fingerprint determinism tests,
+- PDF extraction invariants around `canonicalText`, `pageMap`, and `offsetMap`,
+- tests for whichever browser/session helpers remain in-scope after T04,
+- PDF.js worker/test setup for Node-based runs.
+
+Also decide fixture ownership:
+
+- copy the PDF fixture corpus into this repo,
+- or define a stable shared-fixture path that does not make this repo's tests
+  implicitly depend on the umbrella app layout.
+
+Acceptance: `evidence-source` has its own subsystem test suite, while the
+source-to-anchor round-trip remains an umbrella integration test.
+
+## T06 — Switch `citation-evidence` to the Extracted Repo
+
+```task
+id: ESRC-WP-0001-T06
+status: todo
+priority: high
+```
+
+Finish the extraction by making the umbrella consume this repo instead of its
+local `src/source/` implementation.
+
+Required steps:
+
+- add `@citation-evidence/evidence-source` or equivalent local-link dependency
+  strategy for sibling development,
+- replace local source imports in `citation-evidence` with imports from this
+  repo,
+- keep the existing source-to-anchor integration test upstream and make it run
+  across the repo boundary,
+- remove or tombstone the extracted local source files once downstream is green.
+
+Acceptance: the umbrella app and its integration tests use the extracted source
+package rather than the local `src/source/` copy for the PDF slice.
+
+## T07 — Finish Repo Docs and Queue the Next Workplans
+
+```task
+id: ESRC-WP-0001-T07
+status: todo
+priority: medium
+```
+
+Once the PDF extraction lands, make the repo describe its actual state.
+
+Update:
+
+- `README.md` to reflect real install/dev usage,
+- `SCOPE.md` to replace placeholders with the actual current boundary,
+- registry metadata so this repo no longer advertises "intent only" if it now
+  provides reusable ingest functionality.
+
+Then split the deferred work into separate workplans rather than growing this
+file indefinitely:
+
+- Markdown/HTML representations,
+- metadata enrichment beyond current pass-through options,
+- local citation recovery and external source discovery hooks.
+
+Acceptance: this repo no longer presents itself as an empty placeholder, and
+the next feature phases have their own workplan files.

workplans/ESRC-WP-0001-intent-placeholder.md

@@ -1,19 +0,0 @@
----
-id: ESRC-WP-0001
-type: workplan
-title: "INTENT placeholder — await extraction from citation-evidence"
-domain: infotech
-repo: evidence-source
-status: backlog
-owner: codex
-topic_slug: citation_evidence_mvp
-created: "2026-06-21"
-updated: "2026-06-21"
-state_hub_workstream_id: "64771b5d-4b83-4848-a562-4b00aad017b2"
----
-
-# ESRC-WP-0001 — INTENT Placeholder
-
-Umbrella-first MVP: source/ingestion code will extract from `citation-evidence`
-when the subsystem boundary stabilizes. This file satisfies ADR-001 workplan
-structure until then. See `INTENT.md`.