diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md index e791335..666880d 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/ESRC-WP-0001-bootstrap-standalone-source-repo.md b/workplans/ESRC-WP-0001-bootstrap-standalone-source-repo.md new file mode 100644 index 0000000..747317c --- /dev/null +++ b/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. diff --git a/workplans/ESRC-WP-0001-intent-placeholder.md b/workplans/ESRC-WP-0001-intent-placeholder.md deleted file mode 100644 index d0077f6..0000000 --- a/workplans/ESRC-WP-0001-intent-placeholder.md +++ /dev/null @@ -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`. \ No newline at end of file