Post WP-0002/0003 hygiene: update docs and archive finished workplans
Refresh README and SCOPE to reflect stale/fuzzy/DOM capabilities. Move EANCH-WP-0001 through EANCH-WP-0003 to workplans/archived/260709-*.
This commit is contained in:
parent
a1af0c6a45
commit
113358c13c
5 changed files with 30 additions and 33 deletions
448
workplans/archived/260709-EANCH-WP-0001-intent-placeholder.md
Normal file
448
workplans/archived/260709-EANCH-WP-0001-intent-placeholder.md
Normal file
|
|
@ -0,0 +1,448 @@
|
|||
---
|
||||
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: finished
|
||||
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
|
||||
|
||||
## 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`,
|
||||
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
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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
|
||||
|
||||
```task
|
||||
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`.
|
||||
|
|
@ -0,0 +1,125 @@
|
|||
---
|
||||
id: EANCH-WP-0002
|
||||
type: workplan
|
||||
title: "Anchor resolution hardening: stale/orphan semantics, fuzzy re-anchoring, production PDF adapter"
|
||||
domain: infotech
|
||||
repo: evidence-anchor
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: citation_evidence_mvp
|
||||
created: "2026-07-08"
|
||||
updated: "2026-07-09"
|
||||
spec_refs:
|
||||
- INTENT.md
|
||||
- SCOPE.md
|
||||
- ../citation-evidence/wiki/SharedContracts.md
|
||||
- ../citation-evidence/wiki/ArchitectureOverview.md
|
||||
state_hub_workstream_id: "2e1ad557-11d9-4e5c-8743-973002482a0c"
|
||||
---
|
||||
|
||||
# EANCH-WP-0002 — Anchor Resolution Hardening
|
||||
|
||||
## Goal
|
||||
|
||||
Close the resolution-quality gaps left open by the MVP extraction
|
||||
(`EANCH-WP-0001`) on the **existing PDF/text path**. The extracted slice
|
||||
resolves exact position/quote/PDF selectors with a fixed confidence ladder and
|
||||
returns `resolved | ambiguous | unresolved`. `INTENT.md` promises more:
|
||||
`stale` detection, orphaned-annotation handling, fuzzy/recovery re-anchoring,
|
||||
and human-confirmation workflows for ambiguity. This workplan makes those real
|
||||
without changing the shared selector *types* (those stay in `citation-engine`).
|
||||
|
||||
Non-goals: HTML/Markdown selectors (see `EANCH-WP-0003`); new persistence or
|
||||
UI shell behavior.
|
||||
|
||||
## Background
|
||||
|
||||
Current extracted behavior (`src/selectors/resolve.ts`):
|
||||
|
||||
- confidence ladder 1.00 → 0.70 across TextPosition/TextQuote/PdfPageText/PdfRect
|
||||
- multiple undisambiguated quote matches → `ambiguous` at 0.5
|
||||
- nothing matches → `unresolved` at 0.0
|
||||
- there is **no** `stale` path (the `AnnotationResolutionStatus` enum includes
|
||||
`stale`, but resolve.ts never returns it) and **no** fuzzy matching
|
||||
|
||||
## Task Breakdown
|
||||
|
||||
## T01 — Stale vs. unresolved: distinguish "representation changed" from "never found"
|
||||
|
||||
```task
|
||||
id: EANCH-WP-0002-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "940b03ba-4b2f-4d1a-b7bc-72813817549d"
|
||||
```
|
||||
|
||||
Return `stale` (not `unresolved`) when a previously-resolvable anchor no longer
|
||||
matches because the representation's canonical text changed, while the stored
|
||||
quote is still meaningful. Define the signal (e.g. position selector points
|
||||
in-range but slice ≠ quote AND quote no longer found) and preserve the original
|
||||
quote/context on the result. Add unit tests covering stale vs. unresolved.
|
||||
|
||||
## T02 — Orphaned-annotation detection surface
|
||||
|
||||
```task
|
||||
id: EANCH-WP-0002-T02
|
||||
status: done
|
||||
priority: medium
|
||||
depends_on: [T01]
|
||||
state_hub_task_id: "f75b94cd-bfb8-47f9-bd89-0d605f925290"
|
||||
```
|
||||
|
||||
Give callers a way to identify annotations whose selectors can no longer be
|
||||
placed at all (orphaned) versus stale-but-recoverable. Decide whether this is a
|
||||
distinct status, a flag on `AnchorResolution`, or a helper. Keep the shared
|
||||
enum unchanged unless a contract change is agreed in the umbrella wiki first.
|
||||
|
||||
## T03 — Fuzzy / recovery re-anchoring
|
||||
|
||||
```task
|
||||
id: EANCH-WP-0002-T03
|
||||
status: done
|
||||
priority: high
|
||||
depends_on: [T01]
|
||||
state_hub_task_id: "8548fa44-5bb3-40cf-b8f8-e745deae7dda"
|
||||
```
|
||||
|
||||
Add a fuzzy quote-matching fallback (bounded edit-distance / token overlap)
|
||||
below the exact ladder, returning candidates at appropriately low confidence
|
||||
with `ambiguous`/`stale` status. Must never silently emit a confident wrong
|
||||
match (INTENT: "No Silent Misleading Match"). Add tests with lightly-edited
|
||||
source text. Confirm the ladder's exact tiers are untouched above the fuzzy
|
||||
floor.
|
||||
|
||||
## T04 — Promote the PDF spike to a production adapter
|
||||
|
||||
```task
|
||||
id: EANCH-WP-0002-T04
|
||||
status: done
|
||||
priority: medium
|
||||
depends_on: [T03]
|
||||
state_hub_task_id: "6a7163f5-39ca-48fa-8941-8459c563198f"
|
||||
```
|
||||
|
||||
Turn `PdfSpikeViewer` into a supported `PDFViewerAdapter` that implements the
|
||||
`DocumentViewerAdapter` contract cleanly (remove spike-only debug flags from the
|
||||
public surface, or gate them), keep viewer libs behind `src/pdf/`, and keep the
|
||||
umbrella green through the change. Update `evidence-anchor/pdf` exports and docs.
|
||||
|
||||
## T05 — Verification + close-out
|
||||
|
||||
```task
|
||||
id: EANCH-WP-0002-T05
|
||||
status: done
|
||||
priority: high
|
||||
depends_on: [T02, T04]
|
||||
state_hub_task_id: "1ea0885a-c541-438f-a4fd-b8be0773b373"
|
||||
```
|
||||
|
||||
`pnpm test`/`typecheck`/`lint` green here; umbrella typecheck/test/build green
|
||||
after any contract-visible change; `fix-consistency` clean; progress note.
|
||||
|
||||
**Verification (2026-07-09):**
|
||||
|
||||
- `evidence-anchor`: 42 tests (9 files), typecheck + lint clean.
|
||||
- `citation-evidence`: typecheck clean, 51 integration tests passed.
|
||||
121
workplans/archived/260709-EANCH-WP-0003-non-pdf-selectors.md
Normal file
121
workplans/archived/260709-EANCH-WP-0003-non-pdf-selectors.md
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
id: EANCH-WP-0003
|
||||
type: workplan
|
||||
title: "Non-PDF selectors: HTML/Markdown DOM range + structural anchoring"
|
||||
domain: infotech
|
||||
repo: evidence-anchor
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: citation_evidence_mvp
|
||||
created: "2026-07-08"
|
||||
updated: "2026-07-09"
|
||||
spec_refs:
|
||||
- INTENT.md
|
||||
- SCOPE.md
|
||||
- ../citation-evidence/wiki/SharedContracts.md
|
||||
- ../citation-evidence/docs/decisions/ADR-0006-selector-ownership-split.md
|
||||
state_hub_workstream_id: "04f8a4b7-41fe-4546-8471-364a8b9a6c26"
|
||||
---
|
||||
|
||||
# EANCH-WP-0003 — Non-PDF Selectors (HTML / Markdown)
|
||||
|
||||
## Goal
|
||||
|
||||
Extend anchoring beyond PDFs to non-paginated documents (HTML, Markdown),
|
||||
delivering the `DomRangeSelector` and `StructuralSelector` concepts that
|
||||
`INTENT.md` names but the MVP left as `never`. The extracted package already
|
||||
models format-neutral resolution (`DocumentViewerAdapter`, canonical-text
|
||||
selectors); this workplan fills in the DOM branch of `SelectionCapture` and a
|
||||
concrete HTML/Markdown viewer adapter.
|
||||
|
||||
Depends on the extraction (`EANCH-WP-0001`) being complete. Independent of the
|
||||
resolution-hardening track (`EANCH-WP-0002`) except where both touch the shared
|
||||
enum — coordinate contract changes in the umbrella wiki first.
|
||||
|
||||
## Background
|
||||
|
||||
- `src/types.ts`: `DomSelectionCapture = never` (reserved) — the capture union
|
||||
only has a PDF branch today.
|
||||
- `citation-engine` shared selector types already declare `DomRangeSelector`
|
||||
and `StructuralSelector` as `never` placeholders; promoting them is a
|
||||
shared-contract change and must land in `citation-engine` first (ADR-0006:
|
||||
selector *types* live in engine).
|
||||
|
||||
## Task Breakdown
|
||||
|
||||
## T01 — Contract: promote DomRange/Structural selector types in citation-engine
|
||||
|
||||
```task
|
||||
id: EANCH-WP-0003-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "de7df94f-2ddf-4920-949e-6e693131a9de"
|
||||
```
|
||||
|
||||
Define the real `DomRangeSelector` and `StructuralSelector` shapes (DOM path +
|
||||
range offsets; heading/section/block/AST path) in `citation-engine`'s shared
|
||||
selector module, plus the `DomSelectionCapture` payload contract in the wiki.
|
||||
Land this in the engine + `SharedContracts.md` before writing anchor behavior.
|
||||
|
||||
## T02 — Selector creation from a DOM/Markdown selection
|
||||
|
||||
```task
|
||||
id: EANCH-WP-0003-T02
|
||||
status: done
|
||||
priority: high
|
||||
depends_on: [T01]
|
||||
state_hub_task_id: "aa1bc68d-c15a-41e0-813d-c4ccec4914c9"
|
||||
```
|
||||
|
||||
Implement `createSelectors` for the DOM branch: build TextQuote + TextPosition
|
||||
(against canonical text) plus DomRange + Structural selectors from a captured
|
||||
DOM selection. Add unit tests mirroring the PDF create tests.
|
||||
|
||||
## T03 — Resolution for non-paginated documents
|
||||
|
||||
```task
|
||||
id: EANCH-WP-0003-T03
|
||||
status: done
|
||||
priority: high
|
||||
depends_on: [T02]
|
||||
state_hub_task_id: "2bdedc91-1ed2-41ed-b4a0-a9a0d7a6b4b0"
|
||||
```
|
||||
|
||||
Extend `resolveSelectors` to resolve DomRange/Structural selectors and rank
|
||||
them in the confidence ladder alongside the existing text selectors, keeping
|
||||
paginated (PDF) and non-paginated resolution on shared concepts. Tests for
|
||||
re-render stability (structural fallback when offsets shift).
|
||||
|
||||
## T04 — HTML/Markdown viewer adapter
|
||||
|
||||
```task
|
||||
id: EANCH-WP-0003-T04
|
||||
status: done
|
||||
priority: medium
|
||||
depends_on: [T03]
|
||||
state_hub_task_id: "286267fe-d348-4494-bbe2-dd7818bcadbd"
|
||||
```
|
||||
|
||||
Add a `DocumentViewerAdapter` implementation for rendered HTML/Markdown
|
||||
(selection capture, scroll-to-target, highlight render), behind a subpath
|
||||
export analogous to `evidence-anchor/pdf`, with viewer-specific deps confined
|
||||
to that boundary.
|
||||
|
||||
## T05 — Verification + close-out
|
||||
|
||||
```task
|
||||
id: EANCH-WP-0003-T05
|
||||
status: done
|
||||
priority: high
|
||||
depends_on: [T04]
|
||||
state_hub_task_id: "9ff39c83-eca8-46a1-9b28-8a728ddf220d"
|
||||
```
|
||||
|
||||
Package green (`pnpm test`/`typecheck`/`lint`); engine contract change verified
|
||||
in `citation-engine`; any umbrella consumer green; `fix-consistency` clean;
|
||||
progress note.
|
||||
|
||||
**Verification (2026-07-09):**
|
||||
|
||||
- `citation-engine`: DomRange/Structural types + StructureMap promoted; 89 tests passed.
|
||||
- `evidence-anchor`: DOM create/resolve + `evidence-anchor/dom` export; 42 tests passed.
|
||||
Loading…
Add table
Add a link
Reference in a new issue