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
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue