Files

tegwick 8607c252c4 Implement CE-WP-0003 T01-T08: form binding + visual guide overlay

T01 EvidenceLink/EvidenceSet types
  - src/shared/evidence-link.ts: status (§2.4), relation (§2.5), target
  - src/shared/evidence-set.ts: ordered group + activeEvidenceItemId
  - enum-conformance test parses SharedContracts.md and asserts the
    runtime lists match exactly

T02 Binding service + in-memory link repo + active-state machine
  - src/binder/repos/in-memory-links.ts: Map-backed EvidenceLinkRepository
  - src/binder/services/bindings.ts: link/unlink/list/update/setActive
    emitting §4 EvidenceLinkCreated / EvidenceLinkUpdated /
    EvidenceItemActivated
  - src/binder/state/active.ts: (target, evidence, annotation) reducer
    + ActiveStateProvider + useActiveState hook
  - extended engine/events/types.ts with EvidenceLinkCreated,
    EvidenceLinkUpdated, FormFieldActivated payloads

T03 Rect registry (SharedContracts §7 — contract FROZEN)
  - src/binder/visual-guide/rect-registry.ts: register/getRect/subscribe
    + invalidate + getVersion for useSyncExternalStore
  - events.ts: scroll/resize/focus pumps via window + ResizeObserver +
    IntersectionObserver, rAF-throttled
  - react-hooks.ts: RectRegistryProvider, useRegisterRect(kind,id,ref),
    useRectRegistryVersion

T04 Form schema + renderer
  - src/app/forms/demo-schema.ts: text/textarea/date minimal schema
  - src/binder/FormRenderer.tsx: renders schema, each field registers
    as rect kind="field"; active field gets aria-current="true"
  - placed in binder/ (not work/) because work cannot import binder per
    DependencyMap.md §2 and the renderer needs the rect-registry hook;
    workplan T04 was amended in-place to document this

T05 Side-by-side Forms layout + click-to-link
  - src/app/forms/FormsApp.tsx + src/app/App.tsx top-bar router with
    hash route #/forms/demo
  - BinderProvider mounted at app root so links survive tab switching
  - stage-evidence-then-click-field linking interaction with banner
    + per-field link-count chip

T06 Active-evidence cycling
  - src/app/forms/ActiveEvidenceChips.tsx: chips per active target,
    Tab cycles natively, first chip auto-activates on field focus,
    each chip registers as rect kind="evidence-card"
  - ScrollBridge in FormsApp wires activeAnnotationId to viewer scroll
  - EvidenceSidebar + EvidenceStrip highlight the active item via the
    new useLastActivatedEvidence hook in work/EngineContext

T07 SVG visual-guide overlay
  - src/binder/visual-guide/Overlay.tsx: single fixed-positioned SVG,
    draws field→card and card→highlight bezier curves for the active
    triple, rAF-throttled via the registry
  - src/anchor exposes getHighlightClientRects(annotationId); the
    spike viewer wraps highlights in [data-highlight-id] so the helper
    can locate them
  - src/app/forms/HighlightRectBridge.tsx: registers the active
    annotation's rect via that helper

T08 End-to-end test (PRD scenario steps 5-9)
  - tests/integration/forms-overlay-e2e.dom.test.tsx: full path from
    Review-mode capture through Forms-mode link to active triple +
    aria-current assertions + 2 SVG paths in the overlay
  - additional integration coverage: forms-link-flow + forms-active-cycling

Gates: typecheck ✓ · lint ✓ · build ✓ · 152/152 tests across 21 files.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-25 15:53:17 +02:00

CE-WP-0001-foundations.md

Implement CE-WP-0001 Foundations: TS scaffold, lint boundaries, normalize v1, fixtures

2026-05-25 00:13:03 +02:00

CE-WP-0002-pdf-review-slice.md

Implement CE-WP-0002 T03-T09: ingest, anchor resolution, engine, UI, persistence, e2e

2026-05-25 10:58:11 +02:00

CE-WP-0003-form-binding-visual-guide.md

Implement CE-WP-0003 T01-T08: form binding + visual guide overlay

2026-05-25 15:53:17 +02:00

CE-WP-0004-citation-card-export.md

Wire workplans to state-hub: topic, 4 workstreams, 29 tasks (UUIDs in frontmatter + task blocks)

2026-05-24 17:07:58 +02:00

README.md

Establish shared-contracts home, dependency map, MVP workplans, and umbrella-first strategy

2026-05-24 16:42:25 +02:00

README.md

MVP Workplans

These four workplans implement the first reference scenario from wiki/ProductRequirementsDocument.md §20 — end-to-end PDF evidence capture → form binding → citation card export — entirely inside the citation-evidence repository.

Workplan	Title	Status
`CE-WP-0001`	Foundations — scaffold, folders, lint rules, normalize, fixtures	todo
`CE-WP-0002`	PDF review slice — engine types, anchor, source, viewer, sidebar	todo
`CE-WP-0003`	Form binding + visual guide — EvidenceLink, rect registry, overlay	todo
`CE-WP-0004`	Citation card export — Markdown + HTML renderers, sidebar export	todo

Order

Strictly sequential. CE-WP-0002 depends on the folder/lint scaffolding from CE-WP-0001. CE-WP-0003 and CE-WP-0004 depend on the engine types, viewer adapter, and sidebar from CE-WP-0002.

How to run a workplan

/ralph-workplan workplans/CE-WP-0001-foundations.md

Ralph drives the loop and retires automatically when all tasks in the workplan are marked done. See ~/.claude/plugins/ralph-workplan/ralph-workplan.md.

Acceptance for MVP

The first reference scenario from PRD §20 runs end-to-end:

Create a collection
Upload a PDF
Select a passage, add commentary, create an evidence item
Open a side-by-side form
Link the evidence item to a form field
Focus the field → field, evidence card, and PDF passage all highlighted
SVG guide visible between field → card → highlight
Export evidence as a Markdown citation card