--- id: EANCH-WP-0001 type: workplan title: "Bootstrap evidence-anchor and extract the current anchor slice from citation-evidence" domain: infotech repo: evidence-anchor status: active owner: codex topic_slug: citation_evidence_mvp created: "2026-06-21" updated: "2026-07-08" state_hub_workstream_id: "69e30105-ace2-49b6-a1de-a509052854c1" spec_refs: - INTENT.md - README.md - SCOPE.md - ../citation-evidence/wiki/SharedContracts.md - ../citation-evidence/wiki/DependencyMap.md - ../citation-evidence/docs/decisions/ADR-0006-selector-ownership-split.md --- # EANCH-WP-0001 — Bootstrap And Extract Evidence Anchor Repo review on 2026-07-08 found that `evidence-anchor` is still docs-only: - local repo contents are `INTENT.md`, `README.md`, a template `SCOPE.md`, registry metadata, and this workplan - the concrete implementation currently lives in `../citation-evidence/src/anchor/` - that upstream slice already contains selector creation/resolution logic, PDF selector math, a PDF viewer adapter spike, scroll/highlight helpers, and unit tests - `../citation-engine` already exports the shared `Document`, `DocumentRepresentation`, `Selector`, `AnnotationResolutionStatus`, and `normalize()` surfaces the extracted code needs This workplan replaces the placeholder with a real extraction plan. The first goal is not new feature work; it is to give this repo a real package, move the existing anchor behavior here without breaking the ecosystem boundary, and only then close the gaps between current code and the broader intent documented in `INTENT.md`. ## Execution Order ```text T01 boundary + package shape -> T02 repo bootstrap -> T03 pure selector/resolution extraction -> T04 PDF adapter extraction -> T05 citation-evidence cutover -> T06 stale/orphan/re-anchoring semantics -> T07 HTML/Markdown expansion plan ``` ## T01 — Codify the repo boundary and initial package shape ```task id: EANCH-WP-0001-T01 priority: high status: todo state_hub_task_id: "ef88ff6a-590f-4858-a674-33f84c1d6116" ``` Turn the repo from an intent bucket into a concrete extraction target. Scope: - finish `SCOPE.md` so it reflects the actual boundary described in `INTENT.md`, `SharedContracts.md`, and `ADR-0006` - update `README.md` so it no longer points only at upstream ownership, but states the package/API shape this repo is preparing to expose - document the initial module layout for the first extracted version (`selectors`, `resolver`, `pdf`, `highlight`, `tests`, public entrypoints) - record what explicitly stays out of scope for this phase: persistence, binder/work semantics, ingestion, and umbrella app shell Done when this repo has an unambiguous written contract for what code moves here and what continues to belong to `citation-engine` and downstream repos. ## T02 — Bootstrap the local TypeScript package and test harness ```task id: EANCH-WP-0001-T02 status: todo priority: high depends_on: [T01] state_hub_task_id: "59c07bc6-7a80-4f58-b1cf-ee2f0c26e8ed" ``` Create the minimum package scaffolding needed to host extracted code. Scope: - add `package.json`, `tsconfig.json`, lint/test scripts, and a test runner consistent with sibling repos - define public exports for the package and for any subpath exports that need to stay stable during cutover - wire imports to `@citation-evidence/engine/shared` instead of local `@shared/*` aliases from the umbrella repo - ensure the repo can typecheck and run tests without importing `citation-evidence` internals Done when this repo can host TypeScript source and tests as a standalone package with only `citation-engine` as a shared-type dependency. ## T03 — Extract pure selector creation and resolution logic ```task id: EANCH-WP-0001-T03 status: todo priority: critical depends_on: [T02] state_hub_task_id: "d7bff928-a022-4cc4-a151-950ffaaf622b" ``` Move the non-UI anchoring behavior out of `../citation-evidence/src/anchor/`. Scope: - extract and adapt: `types.ts`, `selectors/create.ts`, `selectors/resolve.ts`, `selectors/index.ts`, `index.ts`, and `pdf-selector-math.ts` - port the matching unit tests: `selectors/create.test.ts`, `selectors/resolve.test.ts`, and `pdf-selector-math.test.ts` - keep the selector-ownership split intact: selector data shapes remain in `citation-engine`, selector behavior lives here - preserve the current exact-match confidence ladder and selector redundancy rules from `SharedContracts.md` Done when the extracted pure modules pass locally in this repo and no longer depend on the umbrella repo folder structure. ## T04 — Extract the PDF viewer adapter and highlight/scroll helpers ```task id: EANCH-WP-0001-T04 status: todo priority: high depends_on: [T03] state_hub_task_id: "1deca610-8502-44e5-90c7-43e355489f55" ``` Move the PDF-specific adapter surface into this repo without leaking viewer library types into engine/shared layers. Scope: - extract and adapt: `pdf-viewer-adapter-spike.tsx`, `scroll-job.ts`, `highlight-styles.css`, and `debug-textlayer.css` - decide whether the first local export remains an explicitly-named spike or is promoted to the initial `PDFViewerAdapter` - keep `react-pdf-highlighter-plus` and PDF.js imports confined to the adapter package boundary - port `scroll-job.test.ts` and add a local demo or harness that still proves select -> store selectors -> resolve -> scroll -> highlight Done when the PDF adapter contract is owned here and the viewer-specific implementation remains behind `DocumentViewerAdapter`. ## T05 — Cut citation-evidence over to the extracted package ```task id: EANCH-WP-0001-T05 status: todo priority: high depends_on: [T03, T04] state_hub_task_id: "2fd9bd62-5d79-49b5-aee7-45e0a37313ba" ``` Replace the umbrella repo's internal anchor slice with a dependency on this repo. Scope: - update `../citation-evidence` to consume `evidence-anchor` through a linked package dependency instead of `src/anchor/` as the source of truth - remove duplicate anchor logic from `citation-evidence` or reduce it to thin compatibility re-exports during transition - verify `citation-evidence` build/test flows still pass against the extracted package - update cross-repo docs so the ownership statement is no longer aspirational Done when `citation-evidence` can be built and tested against this repo and `src/anchor/` is no longer the canonical home of anchor behavior. ## T06 — Close the documented MVP gaps: stale/orphan semantics and safe re-anchoring ```task id: EANCH-WP-0001-T06 status: todo priority: medium depends_on: [T05] state_hub_task_id: "4e82ee7b-e813-441f-a41f-8f17a75fee57" ``` Current upstream code handles exact resolution plus PDF fallbacks, but it does not yet satisfy the full intent surface promised here. Scope: - implement explicit `stale` handling where representation drift can be distinguished from simple `unresolved` - add orphaned-annotation detection hooks and tests - design and implement the first fuzzy or recovery-oriented re-anchoring path without violating the "no silent misleading match" rule - make confidence/warning semantics explicit for recovered matches Done when the resolver can distinguish exact resolution, ambiguity, staleness, and failure in a way that matches `INTENT.md` and `SharedContracts.md`. ## T07 — Plan and stage non-PDF selector support ```task id: EANCH-WP-0001-T07 status: wait priority: low depends_on: [T06] state_hub_task_id: "e88623a9-38d0-4aeb-a7d7-6ec78342d57b" ``` The current extracted surface is PDF-first. `INTENT.md` also claims future HTML/Markdown and structural anchoring support, which should not be improvised after cutover. Scope: - define the first concrete `DomRangeSelector`, `StructuralSelector`, and `FragmentSelector` adoption plan for this repo - identify which parts belong here versus `evidence-source` document representations - decide the first test fixtures and adapter harness for HTML/Markdown - revisit the capability registry once the repo has reusable behavior rather than intent-only docs Done when the next post-PDF workplan can start from a reviewed plan instead of another placeholder.