diff --git a/workplans/EANCH-WP-0001-intent-placeholder.md b/workplans/EANCH-WP-0001-intent-placeholder.md index 3b5627b..e4935ef 100644 --- a/workplans/EANCH-WP-0001-intent-placeholder.md +++ b/workplans/EANCH-WP-0001-intent-placeholder.md @@ -21,6 +21,38 @@ spec_refs: # 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: + +```text +/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`, @@ -34,11 +66,24 @@ Repo review on 2026-07-08 found that `evidence-anchor` is still docs-only: `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`. +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 @@ -48,10 +93,12 @@ T01 boundary + package shape -> T03 pure selector/resolution extraction -> T04 PDF adapter extraction -> T05 citation-evidence cutover - -> T06 stale/orphan/re-anchoring semantics - -> T07 HTML/Markdown expansion plan + -> T06 register remaining post-extraction gaps + -> T07 verification + state-hub close-out ``` +## Task Breakdown + ## T01 — Codify the repo boundary and initial package shape ```task @@ -74,8 +121,24 @@ Scope: - 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. +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 @@ -100,7 +163,22 @@ Scope: - 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 +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 @@ -134,7 +212,21 @@ Scope: - 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 +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 @@ -157,13 +249,26 @@ Scope: `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` +- 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`. @@ -190,10 +295,24 @@ Scope: 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 +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 — Close the documented MVP gaps: stale/orphan semantics and safe re-anchoring +## T06 — Register the post-extraction gaps instead of expanding the slice ```task id: EANCH-WP-0001-T06 @@ -204,43 +323,71 @@ 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. +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: -- 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 +- 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 -Done when the resolver can distinguish exact resolution, ambiguity, staleness, -and failure in a way that matches `INTENT.md` and `SharedContracts.md`. +Acceptance: -## T07 — Plan and stage non-PDF selector support +- 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. + +## T07 — Verification, sync, and close-out evidence ```task id: EANCH-WP-0001-T07 status: wait -priority: low +priority: high 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. +Close the loop with machine-verifiable evidence and State Hub hygiene. 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 +- 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 -Done when the next post-PDF workplan can start from a reviewed plan instead of -another placeholder. +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".