diff --git a/.custodian-brief.md b/.custodian-brief.md index 0632fc4..68a8960 100644 --- a/.custodian-brief.md +++ b/.custodian-brief.md @@ -2,22 +2,12 @@ # Custodian Brief — evidence-anchor **Domain:** infotech -**Last synced:** 2026-07-08 17:50 UTC +**Last synced:** 2026-06-22 18:27 UTC **State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)* ## Active Workstreams -### Bootstrap evidence-anchor and extract the current anchor slice from citation-evidence -Progress: 0/7 done | workstream_id: `69e30105-ace2-49b6-a1de-a509052854c1` - -**Open tasks:** -- ! T07 — Plan and stage non-PDF selector support `e88623a9` -- · T01 — Codify the repo boundary and initial package shape `ef88ff6a` -- · T02 — Bootstrap the local TypeScript package and test harness `59c07bc6` -- · T03 — Extract pure selector creation and resolution logic `d7bff928` -- · T04 — Extract the PDF viewer adapter and highlight/scroll helpers `1deca610` -- · T05 — Cut citation-evidence over to the extracted package `2fd9bd62` -- · T06 — Close the documented MVP gaps: stale/orphan semantics and safe re-anchoring `4e82ee7b` +*(none — repo may need first-session setup)* --- ## MCP Orientation (when available) diff --git a/workplans/EANCH-WP-0001-intent-placeholder.md b/workplans/EANCH-WP-0001-intent-placeholder.md index 692cbf1..cf3c877 100644 --- a/workplans/EANCH-WP-0001-intent-placeholder.md +++ b/workplans/EANCH-WP-0001-intent-placeholder.md @@ -1,239 +1,19 @@ --- id: EANCH-WP-0001 type: workplan -title: "Bootstrap evidence-anchor and extract the current anchor slice from citation-evidence" +title: "INTENT placeholder — await extraction from citation-evidence" domain: infotech repo: evidence-anchor -status: active +status: backlog owner: codex topic_slug: citation_evidence_mvp created: "2026-06-21" -updated: "2026-07-08" +updated: "2026-06-21" 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 +# EANCH-WP-0001 — INTENT Placeholder -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 - -This workplan replaces the placeholder with a real extraction plan. The first -goal is not new feature work; it is to give this repo a real package, -move the existing anchor behavior here without breaking the ecosystem -boundary, and only then close the gaps between current code and the broader -intent documented in `INTENT.md`. - -## Execution Order - -```text -T01 boundary + package shape - -> T02 repo bootstrap - -> T03 pure selector/resolution extraction - -> T04 PDF adapter extraction - -> T05 citation-evidence cutover - -> T06 stale/orphan/re-anchoring semantics - -> T07 HTML/Markdown expansion plan -``` - -## T01 — Codify the repo boundary and initial package shape - -```task -id: EANCH-WP-0001-T01 -priority: high -status: todo -``` - -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 - -Done when this repo has an unambiguous written contract for what code moves -here and what continues to belong to `citation-engine` and downstream repos. - -## T02 — Bootstrap the local TypeScript package and test harness - -```task -id: EANCH-WP-0001-T02 -status: todo -priority: high -depends_on: [T01] -``` - -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 - -Done when this repo can host TypeScript source and tests as a standalone -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: todo -priority: critical -depends_on: [T02] -``` - -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` - -Done when the extracted pure 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: todo -priority: high -depends_on: [T03] -``` - -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 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 - -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: todo -priority: high -depends_on: [T03, T04] -``` - -Replace the umbrella repo's internal anchor slice with a dependency on this -repo. - -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 - -Done when `citation-evidence` can be built and tested against this repo and -`src/anchor/` is no longer the canonical home of anchor behavior. - -## T06 — Close the documented MVP gaps: stale/orphan semantics and safe re-anchoring - -```task -id: EANCH-WP-0001-T06 -status: todo -priority: medium -depends_on: [T05] -``` - -Current upstream code handles exact resolution plus PDF fallbacks, but it does -not yet satisfy the full intent surface promised here. - -Scope: - -- implement explicit `stale` handling where representation drift can be - distinguished from simple `unresolved` -- add orphaned-annotation detection hooks and tests -- design and implement the first fuzzy or recovery-oriented re-anchoring path - without violating the "no silent misleading match" rule -- make confidence/warning semantics explicit for recovered matches - -Done when the resolver can distinguish exact resolution, ambiguity, staleness, -and failure in a way that matches `INTENT.md` and `SharedContracts.md`. - -## T07 — Plan and stage non-PDF selector support - -```task -id: EANCH-WP-0001-T07 -status: wait -priority: low -depends_on: [T06] -``` - -The current extracted surface is PDF-first. `INTENT.md` also claims future -HTML/Markdown and structural anchoring support, which should not be improvised -after cutover. - -Scope: - -- define the first concrete `DomRangeSelector`, `StructuralSelector`, and - `FragmentSelector` adoption plan for this repo -- identify which parts belong here versus `evidence-source` document - representations -- decide the first test fixtures and adapter harness for HTML/Markdown -- revisit the capability registry once the repo has reusable behavior rather - than intent-only docs - -Done when the next post-PDF workplan can start from a reviewed plan instead of -another placeholder. +Umbrella-first MVP: anchoring code will extract from `citation-evidence` when +the subsystem boundary stabilizes. This file satisfies ADR-001 workplan +structure until then. See `INTENT.md`. \ No newline at end of file