EANCH-WP-0001 T06: register post-extraction gaps as follow-on workplans

Draft two proposed workplans instead of expanding this slice:
- EANCH-WP-0002 anchor-resolution-hardening (stale/orphan, fuzzy re-anchoring,
  promote PdfSpikeViewer to a production PDFViewerAdapter)
- EANCH-WP-0003 non-pdf-selectors (HTML/Markdown DomRange+Structural, non-PDF
  viewer adapter; starts with a citation-engine shared-type contract change)
Add an explicit gap map to WP-0001 T06. fix-consistency (C-06) will register
both in the hub during T07.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-07-08 21:11:24 +02:00
parent f32b500f44
commit 0871f79d2d
3 changed files with 240 additions and 1 deletions

View file

@ -345,7 +345,7 @@ Done when `citation-evidence` builds and tests against this repo and
```task ```task
id: EANCH-WP-0001-T06 id: EANCH-WP-0001-T06
status: todo status: done
priority: medium priority: medium
depends_on: [T05] depends_on: [T05]
state_hub_task_id: "4e82ee7b-e813-441f-a41f-8f17a75fee57" state_hub_task_id: "4e82ee7b-e813-441f-a41f-8f17a75fee57"
@ -384,6 +384,21 @@ Deliverables:
Done when the extracted package ships with an honest, explicit map of the Done when the extracted package ships with an honest, explicit map of the
remaining anchor work instead of vague future intent. 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 ## T07 — Verification, sync, and close-out evidence
```task ```task

View file

@ -0,0 +1,114 @@
---
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: proposed
owner: codex
topic_slug: citation_evidence_mvp
created: "2026-07-08"
updated: "2026-07-08"
spec_refs:
- INTENT.md
- SCOPE.md
- ../citation-evidence/wiki/SharedContracts.md
- ../citation-evidence/wiki/ArchitectureOverview.md
---
# 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: todo
priority: high
```
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: todo
priority: medium
depends_on: [T01]
```
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: todo
priority: high
depends_on: [T01]
```
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: todo
priority: medium
depends_on: [T03]
```
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: todo
priority: high
depends_on: [T02, T04]
```
`pnpm test`/`typecheck`/`lint` green here; umbrella typecheck/test/build green
after any contract-visible change; `fix-consistency` clean; progress note.

View file

@ -0,0 +1,110 @@
---
id: EANCH-WP-0003
type: workplan
title: "Non-PDF selectors: HTML/Markdown DOM range + structural anchoring"
domain: infotech
repo: evidence-anchor
status: proposed
owner: codex
topic_slug: citation_evidence_mvp
created: "2026-07-08"
updated: "2026-07-08"
spec_refs:
- INTENT.md
- SCOPE.md
- ../citation-evidence/wiki/SharedContracts.md
- ../citation-evidence/docs/decisions/ADR-0006-selector-ownership-split.md
---
# 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: todo
priority: high
```
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: todo
priority: high
depends_on: [T01]
```
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: todo
priority: high
depends_on: [T02]
```
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: todo
priority: medium
depends_on: [T03]
```
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: todo
priority: high
depends_on: [T04]
```
Package green (`pnpm test`/`typecheck`/`lint`); engine contract change verified
in `citation-engine`; any umbrella consumer green; `fix-consistency` clean;
progress note.