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

---
id: EBIND-WP-0001
type: workplan
title: "Extract evidence-binder from citation-evidence"
domain: infotech
repo: evidence-binder
status: done
owner: codex
topic_slug: citation_evidence_mvp
created: "2026-06-21"
updated: "2026-07-09"
state_hub_workstream_id: "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

```text
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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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