evidence-binder/workplans/EBIND-WP-0001-intent-placeholder.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
EBIND-WP-0001	workplan	Extract evidence-binder from citation-evidence	infotech	evidence-binder	done	codex	citation_evidence_mvp	2026-06-21	2026-07-09	405d789c-0e0b-4764-89ed-0f6140a143e7

EBIND-WP-0001 — Extract evidence-binder from citation-evidence

Extract ../citation-evidence/src/binder/ into this repository as a standalone package without changing the binder's canonical responsibilities: evidence links, active target/evidence state, and the visual-guide rect registry.

The extracted package must conform to ../citation-evidence/wiki/SharedContracts.md, respect ../citation-evidence/wiki/DependencyMap.md, and remain dependent on citation-engine and evidence-anchor only.

Prerequisites:

• umbrella MVP binder slice already exists in ../citation-evidence/src/binder/
• citation-engine is already extracted and available as a sibling package
• shared contract authority remains in the umbrella docs until binder extraction is complete

Goals

1. This repo becomes the canonical home of the binder implementation.
2. Umbrella behavior remains unchanged after wireup.
3. The extracted package stays target-neutral and does not pick up forbidden citation-work or evidence-source dependencies.
4. Tests, lint, and typecheck are green in both this repo and the umbrella consumer after cutover.

Dependency Order

T01 (boundary + contract lock)
  └─ T02 (toolchain + package scaffold)
       ├─ T03 (headless bindings + provider extraction)
       │    └─ T04 (visual guide extraction)
       ├─ T05 (reference UI surface decision)
       └─ T06 (docs + local contract references)
            └─ T07 (umbrella wireup)
                 └─ T08 (verification + closeout)

---

T01 — Lock extraction boundary and contract deltas

id: EBIND-WP-0001-T01
status: done
priority: high
state_hub_task_id: "f2abe7f8-089b-4719-a739-18dc3224e9eb"

Review the upstream binder slice against the current shared contracts before any code moves:

• services/, repos/, state/, visual-guide/
• BinderProvider.tsx, FormRenderer.tsx, FieldDefinitionForm.tsx
• ../citation-evidence/wiki/SharedContracts.md sections 2.4, 2.5, 4, and 7
• ../citation-evidence/wiki/DependencyMap.md section 2

Resolve or explicitly record:

• INTENT drift around EvidenceTarget naming and target vocabulary
• dropped relation values derived-from / needs-check
• event vocabulary mismatches such as removal semantics versus the canonical bus
• exact files that extract into this repo versus remain umbrella-only

Acceptance:

• extraction inventory is explicit and bounded
• no unresolved contract contradiction remains hidden in INTENT.md
• forbidden dependency edges are called out before code copy starts

T02 — Stand up standalone package, tests, and repo metadata

id: EBIND-WP-0001-T02
status: done
priority: high
state_hub_task_id: "122a254f-6490-4211-bde7-ce515c72c36a"

Create the package scaffold this repo currently lacks:

• package.json with test, lint, and typecheck scripts
• TypeScript, Vitest, and lint config aligned with sibling extracted repos
• entrypoints for binder exports
• repo-local README.md, SCOPE.md, and capability metadata that describe the package as real code rather than INTENT-only placeholder material

Acceptance:

• this repo can install, test, lint, and typecheck as an independent package
• top-level docs describe the extracted package surface and repo boundary
• registry/indexes/capabilities.yaml no longer advertises an empty placeholder

T03 — Extract headless bindings, state, and provider composition

id: EBIND-WP-0001-T03
status: done
priority: high
state_hub_task_id: "d58501a4-b2e5-45fa-b504-e2c37ca48e68"

Extract the non-visual binder core:

• repos/in-memory-links.ts
• services/bindings.ts and its tests
• state/active.ts and its tests
• BinderProvider.tsx
• package exports for the headless service and provider surface

Preserve:

• current query directions (target -> links, evidence -> links)
• default relation/status behavior
• active target / active evidence / active annotation coordination
• bus injection and initialLinks restore behavior

Acceptance:

• headless binder behavior runs in this repo with passing tests
• no persistence, viewer, citation-work, or evidence-source dependency is introduced
• the binder package can mount its provider and expose the current state API

T04 — Extract rect registry, change pumps, and overlay

id: EBIND-WP-0001-T04
status: done
priority: high
depends_on: [T03]
state_hub_task_id: "b6f96550-c4a6-4ce1-bfde-4c91d33da687"

Move the visual-guide contract from ../citation-evidence/src/binder/visual-guide/, including rect-registry.ts, events.ts, react-hooks.ts, Overlay.tsx, and their tests. Preserve the section 7 rect kinds, invalidate/version semantics, requestAnimationFrame throttling, and the contract that independent renderers publish rects into one registry.

Acceptance:

• section 7 rect-registry contract is implemented here without behavioral drift
• overlay redraw behavior still depends on rect invalidation rather than polling
• rect registry, hook, and overlay tests pass from this repo

T05 — Decide binder-owned reference UI surface

id: EBIND-WP-0001-T05
status: done
priority: medium
depends_on: [T03, T04]
state_hub_task_id: "58b55a71-eee4-4f3d-9bcd-7c3678320dd1"

Make an explicit decision for the small React form surface:

• keep FormRenderer.tsx and FieldDefinitionForm.tsx as supported binder exports, or
• move them to examples/reference UI and narrow the package surface accordingly

The decision must preserve the architectural rule that binder is form-friendly but target-neutral and does not depend on citation-work.

Acceptance:

• the repo documents which React UI pieces are contractual versus illustrative
• any retained UI exports compile and test here
• any demoted UI files no longer blur the subsystem boundary

T06 — Refresh docs and local contract references

id: EBIND-WP-0001-T06
status: done
priority: medium
depends_on: [T01, T02]
state_hub_task_id: "39164219-5f35-49cf-874a-00fd0c902007"

Update the repo's local reference material so the extracted package is understandable without reopening the umbrella implementation:

• refresh README.md and SCOPE.md
• update INTENT.md where it still implies placeholder-only state
• add or copy the minimum local contract references needed for conformance
• document the dependency rule: binder may depend on engine and anchor, not on source, work, or umbrella behavior

Acceptance:

• a developer can orient from this repo alone and understand what extracts here
• local docs do not contradict the umbrella shared-contract authority
• repo metadata no longer looks like a pre-extraction stub

T07 — Cut over umbrella integration and verify boundaries

id: EBIND-WP-0001-T07
status: done
priority: high
depends_on: [T04, T05, T06]
state_hub_task_id: "efceaee5-43a8-4ecf-9025-a5843eecada0"

Update citation-evidence to consume the extracted binder package instead of owning src/binder/ directly, or otherwise enforce the same boundary through package-level imports during a staged cutover. Verify there are no forbidden edges to citation-evidence behavior, citation-work, or evidence-source, and keep shared-contract changes flowing through the umbrella docs until the cutover is complete.

Acceptance:

• umbrella resolves binder imports through this repo rather than a duplicate local copy
• binder-specific code is deleted or reduced to package-facing glue in the umbrella repo
• dependency-boundary checks still enforce the allowed edge set after wireup

T08 — Verification and closeout

id: EBIND-WP-0001-T08
status: done
priority: medium
depends_on: [T07]
state_hub_task_id: "2c89dfcb-1526-46d9-936d-8f97f4e48d76"

Verification:

• pnpm test is green in evidence-binder
• pnpm typecheck is green in evidence-binder
• pnpm lint is green in evidence-binder
• umbrella consumer tests/typecheck/lint stay green after wireup
• manual smoke still covers the field -> evidence card -> highlight visual guide path

Acceptance:

• this repo exports the binder service, active-state flow, and rect-registry contract
• umbrella behavior is unchanged on the MVP evidence-backed form flow
• all tasks can be closed individually by a Ralph loop without further task splitting

Out Of Scope

• changing canonical enum vocabularies outside the shared-contract process
• taking ownership of document ingestion, selector resolution, or viewer internals
• making citation-work import binder directly
• publish/distribution work beyond the extraction and sibling-consumer wireup