evidence-anchor/workplans/EANCH-WP-0001-intent-placeholder.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id	spec_refs
EANCH-WP-0001	workplan	Bootstrap evidence-anchor and extract the current anchor slice from citation-evidence	infotech	evidence-anchor	active	codex	citation_evidence_mvp	2026-06-21	2026-07-08	69e30105-ace2-49b6-a1de-a509052854c1	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

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

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

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

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

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

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

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

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.