chore(consistency): sync task status from DB [auto]
Updated by fix-consistency on 2026-07-08: - EANCH-WP-0001-T07: todo → wait
This commit is contained in:
custodian-sync
parent
3530357998
commit
9f95e9d34d
1 changed files with 185 additions and 38 deletions
|
|
@ -21,6 +21,38 @@ spec_refs:
|
|||
|
||||
# EANCH-WP-0001 — Bootstrap And Extract Evidence Anchor
|
||||
|
||||
## Goal
|
||||
|
||||
Turn `evidence-anchor` from an intent-only placeholder into the real home of
|
||||
the current anchor slice that already exists in
|
||||
`../citation-evidence/src/anchor/`, while keeping the extraction bounded enough
|
||||
to run safely under `/ralph-workplan`.
|
||||
|
||||
This workplan is intentionally about **package bootstrap + code extraction +
|
||||
consumer cutover + verification**. It is not the place to invent the full next
|
||||
generation of anchor behavior.
|
||||
|
||||
## Ralph Loop Fit
|
||||
|
||||
Recommended invocation once the repo is ready to execute:
|
||||
|
||||
```text
|
||||
/ralph-workplan workplans/EANCH-WP-0001-intent-placeholder.md --max-iterations 12
|
||||
```
|
||||
|
||||
Guardrails for the loop:
|
||||
|
||||
- stop at extraction/cutover/verification; do not expand into open-ended
|
||||
feature design during the same loop
|
||||
- if stale detection, fuzzy recovery, or HTML/Markdown support turns into
|
||||
substantive new implementation work, register a follow-on workplan instead of
|
||||
growing this one in place
|
||||
- HEUREKA condition for this workplan is: extracted package exists, umbrella
|
||||
consumer is wired to it, verification is green, and the remaining gaps are
|
||||
registered as next work rather than left implicit
|
||||
|
||||
## Background And References
|
||||
|
||||
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`,
|
||||
|
|
@ -34,11 +66,24 @@ Repo review on 2026-07-08 found that `evidence-anchor` is still docs-only:
|
|||
`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`.
|
||||
Relevant upstream files already reviewed:
|
||||
|
||||
- `../citation-evidence/src/anchor/types.ts`
|
||||
- `../citation-evidence/src/anchor/selectors/create.ts`
|
||||
- `../citation-evidence/src/anchor/selectors/resolve.ts`
|
||||
- `../citation-evidence/src/anchor/pdf-selector-math.ts`
|
||||
- `../citation-evidence/src/anchor/pdf-viewer-adapter-spike.tsx`
|
||||
- `../citation-evidence/src/anchor/scroll-job.ts`
|
||||
- matching upstream tests under `../citation-evidence/src/anchor/`
|
||||
|
||||
## Non-Goals For This Ralph Slice
|
||||
|
||||
- full HTML/Markdown selector implementation
|
||||
- a production-grade fuzzy re-anchoring system
|
||||
- new persistence, binder, source-ingest, or workspace-shell behavior
|
||||
- speculative architecture beyond what is needed to extract and verify the
|
||||
existing anchor slice
|
||||
- indefinite cross-repo cleanup without an explicit verification target
|
||||
|
||||
## Execution Order
|
||||
|
||||
|
|
@ -48,10 +93,12 @@ T01 boundary + package shape
|
|||
-> T03 pure selector/resolution extraction
|
||||
-> T04 PDF adapter extraction
|
||||
-> T05 citation-evidence cutover
|
||||
-> T06 stale/orphan/re-anchoring semantics
|
||||
-> T07 HTML/Markdown expansion plan
|
||||
-> T06 register remaining post-extraction gaps
|
||||
-> T07 verification + state-hub close-out
|
||||
```
|
||||
|
||||
## Task Breakdown
|
||||
|
||||
## T01 — Codify the repo boundary and initial package shape
|
||||
|
||||
```task
|
||||
|
|
@ -74,8 +121,24 @@ Scope:
|
|||
- 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.
|
||||
Acceptance:
|
||||
|
||||
- `SCOPE.md` is no longer a template; it names the extracted boundary,
|
||||
current maturity, relevant dependencies, and non-goals
|
||||
- `README.md` explains the package purpose, sibling-checkout install model, and
|
||||
public module layout expectations
|
||||
- the repo docs clearly distinguish:
|
||||
`citation-engine` owns shared selector types;
|
||||
`evidence-anchor` owns selector behavior and viewer contracts
|
||||
|
||||
Deliverables:
|
||||
|
||||
- finished `SCOPE.md`
|
||||
- extraction-oriented `README.md`
|
||||
- concise package shape documented in-repo
|
||||
|
||||
Done when a fresh agent can open this repo and know exactly what should move
|
||||
here and what must stay elsewhere.
|
||||
|
||||
## T02 — Bootstrap the local TypeScript package and test harness
|
||||
|
||||
|
|
@ -100,7 +163,22 @@ Scope:
|
|||
- 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
|
||||
Acceptance:
|
||||
|
||||
- the scaffold matches the existing `citation-engine` conventions closely
|
||||
enough that extraction is mostly file movement plus import rewrites
|
||||
- `pnpm test`, `pnpm typecheck`, and `pnpm lint` exist as local scripts
|
||||
- the package exposes a stable public entrypoint and any necessary subpath
|
||||
exports for the adapter slice
|
||||
|
||||
Deliverables:
|
||||
|
||||
- `package.json`
|
||||
- `tsconfig.json`
|
||||
- test/lint config files
|
||||
- any required ignore / Node version files
|
||||
|
||||
Done when this repo can host the extracted code as a standalone TypeScript
|
||||
package with only `citation-engine` as a shared-type dependency.
|
||||
|
||||
## T03 — Extract pure selector creation and resolution logic
|
||||
|
|
@ -134,7 +212,21 @@ Scope:
|
|||
- 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
|
||||
Acceptance:
|
||||
|
||||
- the extracted pure modules compile against `@citation-evidence/engine/shared`
|
||||
imports, not umbrella-only aliases
|
||||
- the three upstream unit-test groups pass locally in this repo
|
||||
- no UI/viewer package dependencies are required for this task
|
||||
|
||||
Deliverables:
|
||||
|
||||
- extracted core source files under `src/`
|
||||
- ported unit tests for selector creation, selector resolution, and PDF
|
||||
selector math
|
||||
- local exports wired through the package entrypoint
|
||||
|
||||
Done when the pure anchor 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
|
||||
|
|
@ -157,13 +249,26 @@ Scope:
|
|||
`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`
|
||||
- decide explicitly 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
|
||||
|
||||
Acceptance:
|
||||
|
||||
- viewer-library imports exist only inside the adapter package boundary
|
||||
- the scroll/highlight helper test passes locally
|
||||
- a maintainer can identify the supported PDF adapter surface and its current
|
||||
non-goals from the repo without reading the umbrella repo
|
||||
|
||||
Deliverables:
|
||||
|
||||
- extracted adapter and helper files
|
||||
- local adapter export decision documented in code or README
|
||||
- at least one runnable or inspectable local harness path for the PDF adapter
|
||||
|
||||
Done when the PDF adapter contract is owned here and the viewer-specific
|
||||
implementation remains behind `DocumentViewerAdapter`.
|
||||
|
||||
|
|
@ -190,10 +295,24 @@ Scope:
|
|||
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
|
||||
Acceptance:
|
||||
|
||||
- `citation-evidence/package.json` points at `link:../evidence-anchor` (or the
|
||||
equivalent local consumer path actually chosen)
|
||||
- umbrella imports resolve through the extracted package instead of treating
|
||||
`src/anchor/` as the canonical implementation
|
||||
- `citation-evidence` build/test/typecheck remain green after the cutover
|
||||
|
||||
Deliverables:
|
||||
|
||||
- consumer dependency and import updates in `../citation-evidence`
|
||||
- any temporary compatibility shims reduced to thin re-exports only
|
||||
- updated ownership docs across the affected repos
|
||||
|
||||
Done when `citation-evidence` builds and tests 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
|
||||
## T06 — Register the post-extraction gaps instead of expanding the slice
|
||||
|
||||
```task
|
||||
id: EANCH-WP-0001-T06
|
||||
|
|
@ -204,43 +323,71 @@ state_hub_task_id: "4e82ee7b-e813-441f-a41f-8f17a75fee57"
|
|||
```
|
||||
|
||||
Current upstream code handles exact resolution plus PDF fallbacks, but it does
|
||||
not yet satisfy the full intent surface promised here.
|
||||
not yet satisfy the entire intent promised in `INTENT.md`. Those gaps should be
|
||||
made explicit and queued, not silently folded into this extraction loop.
|
||||
|
||||
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
|
||||
- document the gap between the extracted MVP behavior and the broader
|
||||
`INTENT.md` target for:
|
||||
`stale`,
|
||||
orphaned annotations,
|
||||
fuzzy or recovery-oriented re-anchoring,
|
||||
and HTML/Markdown selectors
|
||||
- decide which gaps belong in one follow-on extraction-hardening workplan
|
||||
versus separate format-specific workplans
|
||||
- write the follow-on plan(s) or clearly register them in this workplan as
|
||||
explicit next slices
|
||||
|
||||
Done when the resolver can distinguish exact resolution, ambiguity, staleness,
|
||||
and failure in a way that matches `INTENT.md` and `SharedContracts.md`.
|
||||
Acceptance:
|
||||
|
||||
## T07 — Plan and stage non-PDF selector support
|
||||
- no major promised behavior remains as "implicit future work"
|
||||
- the next work after extraction is named concretely enough that another Ralph
|
||||
loop can pick it up without re-discovery
|
||||
- the current workplan stays bounded: no new broad implementation starts here
|
||||
|
||||
Deliverables:
|
||||
|
||||
- follow-on workplan section or new workplan file(s) for gap closure
|
||||
- updated references in `README.md`/`SCOPE.md` if they previously implied those
|
||||
features already existed here
|
||||
|
||||
Done when the extracted package ships with an honest, explicit map of the
|
||||
remaining anchor work instead of vague future intent.
|
||||
|
||||
## T07 — Verification, sync, and close-out evidence
|
||||
|
||||
```task
|
||||
id: EANCH-WP-0001-T07
|
||||
status: wait
|
||||
priority: low
|
||||
priority: high
|
||||
depends_on: [T06]
|
||||
state_hub_task_id: "e88623a9-38d0-4aeb-a7d7-6ec78342d57b"
|
||||
```
|
||||
|
||||
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.
|
||||
Close the loop with machine-verifiable evidence and State Hub hygiene.
|
||||
|
||||
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
|
||||
- run the local verification commands for `evidence-anchor`
|
||||
- run the affected verification commands for `citation-evidence` after cutover
|
||||
- update task/workplan status, run `fix-consistency`, and log the required
|
||||
progress note
|
||||
- ensure the repo capability note and brief remain truthful after extraction
|
||||
|
||||
Done when the next post-PDF workplan can start from a reviewed plan instead of
|
||||
another placeholder.
|
||||
Acceptance:
|
||||
|
||||
- `pnpm test`, `pnpm typecheck`, and `pnpm lint` are green in this repo
|
||||
- the relevant `citation-evidence` verification commands are green after
|
||||
consumer cutover
|
||||
- `fix-consistency` passes and the workplan can be moved from `active` to
|
||||
`finished` without status drift
|
||||
|
||||
Deliverables:
|
||||
|
||||
- verification evidence in commit history and/or progress note
|
||||
- synced State Hub task/workplan state
|
||||
- clean handoff for the next anchor follow-on workplan
|
||||
|
||||
Done when the extraction is verified end-to-end and the workplan can retire
|
||||
cleanly under HEUREKA instead of stopping at "probably finished".
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue