From 0871f79d2da65051248de8c654fcd37d8d9d6712 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 8 Jul 2026 21:11:24 +0200 Subject: [PATCH] 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 --- workplans/EANCH-WP-0001-intent-placeholder.md | 17 ++- ...NCH-WP-0002-anchor-resolution-hardening.md | 114 ++++++++++++++++++ workplans/EANCH-WP-0003-non-pdf-selectors.md | 110 +++++++++++++++++ 3 files changed, 240 insertions(+), 1 deletion(-) create mode 100644 workplans/EANCH-WP-0002-anchor-resolution-hardening.md create mode 100644 workplans/EANCH-WP-0003-non-pdf-selectors.md diff --git a/workplans/EANCH-WP-0001-intent-placeholder.md b/workplans/EANCH-WP-0001-intent-placeholder.md index 25f72a3..b8fe3e1 100644 --- a/workplans/EANCH-WP-0001-intent-placeholder.md +++ b/workplans/EANCH-WP-0001-intent-placeholder.md @@ -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 diff --git a/workplans/EANCH-WP-0002-anchor-resolution-hardening.md b/workplans/EANCH-WP-0002-anchor-resolution-hardening.md new file mode 100644 index 0000000..d7a33fe --- /dev/null +++ b/workplans/EANCH-WP-0002-anchor-resolution-hardening.md @@ -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. diff --git a/workplans/EANCH-WP-0003-non-pdf-selectors.md b/workplans/EANCH-WP-0003-non-pdf-selectors.md new file mode 100644 index 0000000..309fb10 --- /dev/null +++ b/workplans/EANCH-WP-0003-non-pdf-selectors.md @@ -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.