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	finished	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

Goal

Turn evidence-anchor from an intent-only placeholder into the real home of the current anchor slice that already exists in ../citation-evidence/src/anchor/, while keeping the extraction bounded enough to run safely under /ralph-workplan.

This workplan is intentionally about package bootstrap + code extraction + consumer cutover + verification. It is not the place to invent the full next generation of anchor behavior.

Ralph Loop Fit

Recommended invocation once the repo is ready to execute:

/ralph-workplan workplans/EANCH-WP-0001-intent-placeholder.md --max-iterations 12

Guardrails for the loop:

• stop at extraction/cutover/verification; do not expand into open-ended feature design during the same loop
• if stale detection, fuzzy recovery, or HTML/Markdown support turns into substantive new implementation work, register a follow-on workplan instead of growing this one in place
• HEUREKA condition for this workplan is: extracted package exists, umbrella consumer is wired to it, verification is green, and the remaining gaps are registered as next work rather than left implicit

Background And References

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

Relevant upstream files already reviewed:

• ../citation-evidence/src/anchor/types.ts
• ../citation-evidence/src/anchor/selectors/create.ts
• ../citation-evidence/src/anchor/selectors/resolve.ts
• ../citation-evidence/src/anchor/pdf-selector-math.ts
• ../citation-evidence/src/anchor/pdf-viewer-adapter-spike.tsx
• ../citation-evidence/src/anchor/scroll-job.ts
• matching upstream tests under ../citation-evidence/src/anchor/

Non-Goals For This Ralph Slice

• full HTML/Markdown selector implementation
• a production-grade fuzzy re-anchoring system
• new persistence, binder, source-ingest, or workspace-shell behavior
• speculative architecture beyond what is needed to extract and verify the existing anchor slice
• indefinite cross-repo cleanup without an explicit verification target

Execution Order

T01 boundary + package shape
  -> T02 repo bootstrap
    -> T03 pure selector/resolution extraction
      -> T04 PDF adapter extraction
        -> T05 citation-evidence cutover
          -> T06 register remaining post-extraction gaps
            -> T07 verification + state-hub close-out

Task Breakdown

T01 — Codify the repo boundary and initial package shape

id: EANCH-WP-0001-T01
priority: high
status: done
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

Acceptance:

• SCOPE.md is no longer a template; it names the extracted boundary, current maturity, relevant dependencies, and non-goals
• README.md explains the package purpose, sibling-checkout install model, and public module layout expectations
• the repo docs clearly distinguish: citation-engine owns shared selector types; evidence-anchor owns selector behavior and viewer contracts

Deliverables:

• finished SCOPE.md
• extraction-oriented README.md
• concise package shape documented in-repo

Done when a fresh agent can open this repo and know exactly what should move here and what must stay elsewhere.

T02 — Bootstrap the local TypeScript package and test harness

id: EANCH-WP-0001-T02
status: done
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

Acceptance:

• the scaffold matches the existing citation-engine conventions closely enough that extraction is mostly file movement plus import rewrites
• pnpm test, pnpm typecheck, and pnpm lint exist as local scripts
• the package exposes a stable public entrypoint and any necessary subpath exports for the adapter slice

Deliverables:

• package.json
• tsconfig.json
• test/lint config files
• any required ignore / Node version files

Done when this repo can host the extracted code as a standalone TypeScript package with only citation-engine as a shared-type dependency.

T03 — Extract pure selector creation and resolution logic

id: EANCH-WP-0001-T03
status: done
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

Acceptance:

• the extracted pure modules compile against @citation-evidence/engine/shared imports, not umbrella-only aliases
• the three upstream unit-test groups pass locally in this repo
• no UI/viewer package dependencies are required for this task

Deliverables:

• extracted core source files under src/
• ported unit tests for selector creation, selector resolution, and PDF selector math
• local exports wired through the package entrypoint

Done when the pure anchor 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: done
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 explicitly 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

Acceptance:

• viewer-library imports exist only inside the adapter package boundary
• the scroll/highlight helper test passes locally
• a maintainer can identify the supported PDF adapter surface and its current non-goals from the repo without reading the umbrella repo

Deliverables:

• extracted adapter and helper files
• local adapter export decision documented in code or README
• at least one runnable or inspectable local harness path for the PDF adapter

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: done
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.

RESOLVED (2026-07-08). The parallel evidence-source extraction landed (citation-evidence@4ede979), leaving main clean. The cutover was then executed and verified: umbrella typecheck + 95 tests + production build all green (citation-evidence@d145148). Package published as @citation-evidence/evidence-anchor with ., ./selectors, ./types, and ./pdf exports; node-env consumers use the pure subpaths. Original blocker context retained below.

BLOCKED (2026-07-08, ralph loop iteration). Extraction T01–T04 are complete, committed, and verified green in evidence-anchor (30 tests, typecheck, lint). T05 was not attempted because the umbrella (../citation-evidence) has another session's uncommitted work in progress on main — a parallel evidence-source extraction: package.json adds @citation-evidence/evidence-source (link), src/source/pdf/* is deleted, and tests/integration/anchor-source-roundtrip.test.ts is already modified — the same shared file this cutover must edit (it imports both @anchor/* and the new source package). Forcing the anchor cutover into that dirty tree would entangle the two extractions and likely commit a non-building intermediate state. Needs human coordination: land/park the source extraction first, or agree how the two cutovers share the roundtrip test and package.json. The ralph loop was deactivated at this point.

Cutover plan once unblocked (bounded — 4 import sites, all via @anchor/index): add "evidence-anchor": "link:../evidence-anchor"; repoint PdfSelectionCapture + createSelectors → evidence-anchor, and PdfSpikeViewer/StoredAnnotation + getHighlightClientRects → evidence-anchor/pdf; drop the @anchor tsconfig/vite alias; delete or thin src/anchor/; run umbrella typecheck/test/build.

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

Acceptance:

• citation-evidence/package.json points at link:../evidence-anchor (or the equivalent local consumer path actually chosen)
• umbrella imports resolve through the extracted package instead of treating src/anchor/ as the canonical implementation
• citation-evidence build/test/typecheck remain green after the cutover

Deliverables:

• consumer dependency and import updates in ../citation-evidence
• any temporary compatibility shims reduced to thin re-exports only
• updated ownership docs across the affected repos

Done when citation-evidence builds and tests against this repo and src/anchor/ is no longer the canonical home of anchor behavior.

T06 — Register the post-extraction gaps instead of expanding the slice

id: EANCH-WP-0001-T06
status: done
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 entire intent promised in INTENT.md. Those gaps should be made explicit and queued, not silently folded into this extraction loop.

Scope:

• document the gap between the extracted MVP behavior and the broader INTENT.md target for: stale, orphaned annotations, fuzzy or recovery-oriented re-anchoring, and HTML/Markdown selectors
• decide which gaps belong in one follow-on extraction-hardening workplan versus separate format-specific workplans
• write the follow-on plan(s) or clearly register them in this workplan as explicit next slices

Acceptance:

• no major promised behavior remains as "implicit future work"
• the next work after extraction is named concretely enough that another Ralph loop can pick it up without re-discovery
• the current workplan stays bounded: no new broad implementation starts here

Deliverables:

• follow-on workplan section or new workplan file(s) for gap closure
• updated references in README.md/SCOPE.md if they previously implied those features already existed here

Done when the extracted package ships with an honest, explicit map of the remaining anchor work instead of vague future intent.

Gap map (registered 2026-07-08): the two follow-on workplans below cover everything INTENT.md promises beyond the extracted MVP slice. SCOPE.md already lists these under "Not in this extraction slice"; README.md points here. No promised behavior is left as implicit future work.

• workplans/EANCH-WP-0002-anchor-resolution-hardening.md — stale/orphan semantics, fuzzy/recovery re-anchoring, and promoting PdfSpikeViewer to a production PDFViewerAdapter (existing PDF/text path).
• workplans/EANCH-WP-0003-non-pdf-selectors.md — HTML/Markdown DomRange + Structural selectors and a non-PDF viewer adapter (new format track; starts with a citation-engine shared-type contract change).

Both are status: proposed and will be registered in the hub by fix-consistency (C-06) during T07 — not by hand.

T07 — Verification, sync, and close-out evidence

id: EANCH-WP-0001-T07
status: done
priority: high
depends_on: [T06]
state_hub_task_id: "e88623a9-38d0-4aeb-a7d7-6ec78342d57b"

Close the loop with machine-verifiable evidence and State Hub hygiene.

Scope:

• run the local verification commands for evidence-anchor
• run the affected verification commands for citation-evidence after cutover
• update task/workplan status, run fix-consistency, and log the required progress note
• ensure the repo capability note and brief remain truthful after extraction

Acceptance:

• pnpm test, pnpm typecheck, and pnpm lint are green in this repo
• the relevant citation-evidence verification commands are green after consumer cutover
• fix-consistency passes and the workplan can be moved from active to finished without status drift

Deliverables:

• verification evidence in commit history and/or progress note
• synced State Hub task/workplan state
• clean handoff for the next anchor follow-on workplan

Done when the extraction is verified end-to-end and the workplan can retire cleanly under HEUREKA instead of stopping at "probably finished".

Verification (2026-07-08):

• evidence-anchor: pnpm test 30 passed (4 files), typecheck clean, lint clean.
• citation-evidence (post-cutover, d145148): pnpm typecheck clean, pnpm test 95 passed (26 files), pnpm build succeeded.

Commits: 08b3105 T01 · 0e93b68 T02 · bd7f56c T03 · 5b77dbd T04 · f32b500 T05 (umbrella d145148) · 0871f79 T06. Workplan frontmatter set to finished; follow-on gaps live in EANCH-WP-0002 and EANCH-WP-0003.