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:
parent
f32b500f44
commit
0871f79d2d
3 changed files with 240 additions and 1 deletions
|
|
@ -345,7 +345,7 @@ Done when `citation-evidence` builds and tests against this repo and
|
|||
|
||||
```task
|
||||
id: EANCH-WP-0001-T06
|
||||
status: todo
|
||||
status: done
|
||||
priority: medium
|
||||
depends_on: [T05]
|
||||
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
|
||||
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
|
||||
|
|
|
|||
114
workplans/EANCH-WP-0002-anchor-resolution-hardening.md
Normal file
114
workplans/EANCH-WP-0002-anchor-resolution-hardening.md
Normal 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.
|
||||
110
workplans/EANCH-WP-0003-non-pdf-selectors.md
Normal file
110
workplans/EANCH-WP-0003-non-pdf-selectors.md
Normal 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue