diff --git a/workplans/EANCH-WP-0001-intent-placeholder.md b/workplans/EANCH-WP-0001-intent-placeholder.md index cf3c877..692cbf1 100644 --- a/workplans/EANCH-WP-0001-intent-placeholder.md +++ b/workplans/EANCH-WP-0001-intent-placeholder.md @@ -1,19 +1,239 @@ --- id: EANCH-WP-0001 type: workplan -title: "INTENT placeholder — await extraction from citation-evidence" +title: "Bootstrap evidence-anchor and extract the current anchor slice from citation-evidence" domain: infotech repo: evidence-anchor -status: backlog +status: active owner: codex topic_slug: citation_evidence_mvp created: "2026-06-21" -updated: "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 — INTENT Placeholder +# EANCH-WP-0001 — Bootstrap And Extract Evidence Anchor -Umbrella-first MVP: anchoring 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 `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 +``` + +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] +``` + +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] +``` + +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] +``` + +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] +``` + +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] +``` + +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] +``` + +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.