generated from coulomb/repo-seed
Seeded INTENT.md
This commit is contained in:
459
INTENT.md
Normal file
459
INTENT.md
Normal file
@@ -0,0 +1,459 @@
|
||||
# INTENT
|
||||
|
||||
## Purpose
|
||||
|
||||
This repository exists to provide the evidence binding layer for the **citation-evidence** ecosystem.
|
||||
|
||||
**evidence-binder** connects evidence items to structured targets such as form fields, claims, requirements, decisions, document sections, tasks, or other information objects.
|
||||
|
||||
It is responsible for answering the binding question:
|
||||
|
||||
> What does this evidence support, explain, contradict, or source?
|
||||
|
||||
---
|
||||
|
||||
## Primary Utility
|
||||
|
||||
The repository provides the model and interaction logic for turning collected evidence into structured support for information work.
|
||||
|
||||
It should make it possible to:
|
||||
|
||||
- link evidence items to form fields,
|
||||
- link evidence items to claims, requirements, decisions, or document sections,
|
||||
- group evidence items into evidence sets,
|
||||
- express relation types such as supports, contradicts, explains, qualifies, or source-for,
|
||||
- track evidence status and confidence per target,
|
||||
- switch between multiple evidence items connected to the same target,
|
||||
- coordinate active target, active evidence item, and active source annotation,
|
||||
- support visual guidance from structured target to evidence to source context.
|
||||
|
||||
This repository turns collected citations into actionable evidence relationships.
|
||||
|
||||
---
|
||||
|
||||
## Intended Users
|
||||
|
||||
Primary users of this repository are developers and agents implementing evidence-backed workflows.
|
||||
|
||||
They include:
|
||||
|
||||
- developers building evidence-backed forms,
|
||||
- developers building claim or requirement review tools,
|
||||
- developers implementing source-backed decision workflows,
|
||||
- developers connecting document evidence to structured data,
|
||||
- coding agents helping users identify, bind, inspect, or validate evidence,
|
||||
- application developers integrating citation-evidence into domain-specific systems.
|
||||
|
||||
End users should experience this repository whenever they see which source passage supports a field, claim, requirement, or decision.
|
||||
|
||||
---
|
||||
|
||||
## Strategic Role
|
||||
|
||||
The strategic role of **evidence-binder** is to make citation-evidence more than a document annotation system.
|
||||
|
||||
Annotations and evidence items become much more valuable when they are connected to the things they justify.
|
||||
|
||||
This repository provides that connection.
|
||||
|
||||
It enables the flow:
|
||||
|
||||
```text
|
||||
Evidence Item
|
||||
→ Evidence Link
|
||||
→ Evidence Target
|
||||
→ Evidence Set
|
||||
→ Supported Field / Claim / Requirement / Decision
|
||||
````
|
||||
|
||||
The repository should make it possible to inspect not only where evidence came from, but also what it is being used for.
|
||||
|
||||
---
|
||||
|
||||
## Core Concept
|
||||
|
||||
The core concept of this repository is the **evidence link**.
|
||||
|
||||
An evidence link connects an evidence item to a structured target with a meaningful relation.
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
Evidence Item A supports Form Field X
|
||||
Evidence Item B contradicts Claim Y
|
||||
Evidence Item C explains Requirement Z
|
||||
Evidence Item D is the source for Decision Q
|
||||
Evidence Item E qualifies Document Section S
|
||||
```
|
||||
|
||||
The evidence link is not just a technical pointer. It expresses an interpretive relationship between source material and structured work.
|
||||
|
||||
---
|
||||
|
||||
## Scope
|
||||
|
||||
This repository should own:
|
||||
|
||||
* evidence-to-target binding model,
|
||||
* evidence link lifecycle,
|
||||
* evidence sets,
|
||||
* target adapters,
|
||||
* relation types,
|
||||
* target evidence status,
|
||||
* field evidence state,
|
||||
* active target and active evidence state,
|
||||
* evidence switching behavior,
|
||||
* evidence completeness indicators,
|
||||
* support for multiple evidence items per target,
|
||||
* support for evidence that supports or contradicts a target,
|
||||
* visual guide model connecting target, evidence card, and source highlight,
|
||||
* interaction contracts for evidence-backed forms and structured review workflows.
|
||||
|
||||
It should provide the binding capabilities consumed by:
|
||||
|
||||
* **citation-evidence** for the integrated workspace,
|
||||
* **citation-work** when collected evidence is prepared for later use,
|
||||
* **citation-engine** through shared domain contracts,
|
||||
* **evidence-anchor** when linked evidence must reopen source context,
|
||||
* **evidence-source** when evidence requires source context metadata.
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope
|
||||
|
||||
This repository should not own the broader system internals.
|
||||
|
||||
Specifically, it should not own:
|
||||
|
||||
* the canonical document and annotation model,
|
||||
* document ingestion,
|
||||
* text extraction,
|
||||
* citation recovery,
|
||||
* low-level selector resolution,
|
||||
* viewer-specific highlighting,
|
||||
* review workspace UI,
|
||||
* citation card rendering internals,
|
||||
* persistence implementation details,
|
||||
* application shell and deployment,
|
||||
* domain-specific form schemas beyond generic target adapters.
|
||||
|
||||
Those responsibilities belong to the appropriate citation-evidence subsystem repositories.
|
||||
|
||||
---
|
||||
|
||||
## Architectural Position
|
||||
|
||||
```text
|
||||
citation-evidence
|
||||
integrated product shell and reference workspace
|
||||
|
||||
citation-engine
|
||||
core domain model, services, persistence contracts
|
||||
|
||||
evidence-binder
|
||||
evidence links, evidence sets, target binding, active evidence state
|
||||
|
||||
citation-work
|
||||
document review and evidence capture workflow
|
||||
|
||||
evidence-anchor
|
||||
selector resolution and source-context highlighting
|
||||
|
||||
evidence-source
|
||||
document ingestion, representations, and source context
|
||||
```
|
||||
|
||||
**evidence-binder** sits between evidence objects and the structured targets that use them.
|
||||
|
||||
It should not define what documents are or how annotations resolve. It should define how evidence is attached to meaningful targets.
|
||||
|
||||
---
|
||||
|
||||
## Primary Workflows
|
||||
|
||||
### 1. Link Evidence to a Form Field
|
||||
|
||||
A user selects an evidence item and attaches it to a form field.
|
||||
|
||||
```text
|
||||
Active Form Field
|
||||
→ Select Evidence Item
|
||||
→ Create Evidence Link
|
||||
→ Mark Relation as supports / explains / source-for
|
||||
→ Update Field Evidence State
|
||||
```
|
||||
|
||||
### 2. Focus Field and Show Evidence
|
||||
|
||||
A user activates a field that has linked evidence.
|
||||
|
||||
```text
|
||||
Focus Form Field
|
||||
→ Load Evidence Set
|
||||
→ Select Active Evidence Item
|
||||
→ Request Source Context
|
||||
→ Highlight Evidence Card
|
||||
→ Highlight Source Annotation
|
||||
```
|
||||
|
||||
### 3. Switch Between Evidence Items
|
||||
|
||||
A target has several evidence items. The user switches between them.
|
||||
|
||||
```text
|
||||
Evidence Set
|
||||
→ Next / Previous Evidence Item
|
||||
→ Update Active Evidence
|
||||
→ Resolve Annotation
|
||||
→ Scroll Source Viewer
|
||||
→ Update Visual Guide
|
||||
```
|
||||
|
||||
### 4. Bind Evidence to a Claim or Requirement
|
||||
|
||||
Evidence is linked to a structured non-form target.
|
||||
|
||||
```text
|
||||
Claim / Requirement / Decision
|
||||
→ Attach Evidence Item
|
||||
→ Set Relation
|
||||
→ Set Status / Confidence
|
||||
→ Make Evidence Traceable
|
||||
```
|
||||
|
||||
### 5. Inspect Evidence Completeness
|
||||
|
||||
A user or agent checks whether a target has sufficient evidence.
|
||||
|
||||
```text
|
||||
Target
|
||||
→ Load Evidence Links
|
||||
→ Evaluate Required Evidence Policy
|
||||
→ Show none / candidate / confirmed / conflicting / insufficient
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Target Model
|
||||
|
||||
The repository should support generic evidence targets.
|
||||
|
||||
Initial target types may include:
|
||||
|
||||
```text
|
||||
form-field
|
||||
claim
|
||||
requirement
|
||||
decision
|
||||
document-section
|
||||
task
|
||||
record-field
|
||||
```
|
||||
|
||||
The model should not assume that all targets are form fields.
|
||||
|
||||
A target should be addressable through a generic structure such as:
|
||||
|
||||
```ts
|
||||
type EvidenceTarget = {
|
||||
type: string;
|
||||
id: string;
|
||||
label?: string;
|
||||
context?: Record<string, unknown>;
|
||||
};
|
||||
```
|
||||
|
||||
This allows domain-specific systems to add their own target types without changing the core binding model.
|
||||
|
||||
---
|
||||
|
||||
## Relation Types
|
||||
|
||||
Initial evidence relations may include:
|
||||
|
||||
```text
|
||||
supports
|
||||
contradicts
|
||||
explains
|
||||
source-for
|
||||
qualifies
|
||||
context-for
|
||||
derived-from
|
||||
needs-check
|
||||
```
|
||||
|
||||
The first version should keep relation types simple but explicit.
|
||||
|
||||
The relation should describe how the evidence item is being used with respect to the target.
|
||||
|
||||
---
|
||||
|
||||
## Evidence State
|
||||
|
||||
The repository should support target-specific evidence state.
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
no-evidence
|
||||
candidate-evidence
|
||||
confirmed-evidence
|
||||
conflicting-evidence
|
||||
insufficient-evidence
|
||||
needs-review
|
||||
verified
|
||||
```
|
||||
|
||||
An evidence item may be generally confirmed, but its relationship to a specific target may still need review.
|
||||
|
||||
Therefore, evidence item status and evidence link status should be distinguishable.
|
||||
|
||||
---
|
||||
|
||||
## Visual Guide Concept
|
||||
|
||||
For evidence-backed form and structured review workflows, the user should be able to visually understand the connection between:
|
||||
|
||||
```text
|
||||
structured target
|
||||
→ evidence item / citation card
|
||||
→ source annotation / highlighted passage
|
||||
```
|
||||
|
||||
The repository should own the model and interaction state for this visual guide, not necessarily the final rendering implementation.
|
||||
|
||||
A visual guide may use:
|
||||
|
||||
```text
|
||||
active target rect
|
||||
active evidence card rect
|
||||
active annotation rect
|
||||
connector state
|
||||
focus state
|
||||
hover state
|
||||
selection state
|
||||
```
|
||||
|
||||
Rendering may be done by an application layer using SVG, canvas, or DOM overlays.
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
### Evidence Links Are First-Class
|
||||
|
||||
A binding between evidence and target is not just metadata. It is a meaningful domain object.
|
||||
|
||||
### Evidence Is Reusable
|
||||
|
||||
The same evidence item may support multiple targets.
|
||||
|
||||
### Targets Are Generic
|
||||
|
||||
The model should support form fields first, but not be limited to forms.
|
||||
|
||||
### Relation Is Explicit
|
||||
|
||||
The system should distinguish evidence that supports, contradicts, explains, qualifies, or merely sources a target.
|
||||
|
||||
### Active State Is Shared
|
||||
|
||||
Evidence-backed workflows require coordinated active state across field, evidence item, and document highlight.
|
||||
|
||||
### Source Context Remains External
|
||||
|
||||
The repository should request source context through **citation-engine** and **evidence-anchor**, not resolve highlights itself.
|
||||
|
||||
### UI Logic Should Be Portable
|
||||
|
||||
The binding model should be reusable in different interfaces: forms, claim review, requirements tools, audit trails, and reports.
|
||||
|
||||
### Agent Compatibility
|
||||
|
||||
Evidence links should be machine-readable so agents can inspect missing evidence, weak evidence, contradictions, and unsupported fields.
|
||||
|
||||
---
|
||||
|
||||
## Expected Dependencies
|
||||
|
||||
This repository is expected to depend on shared types and contracts from:
|
||||
|
||||
```text
|
||||
citation-engine
|
||||
EvidenceItem, EvidenceLink, EvidenceSet, CitationTarget, service contracts
|
||||
```
|
||||
|
||||
It may interact with:
|
||||
|
||||
```text
|
||||
evidence-anchor
|
||||
to request source resolution for active evidence
|
||||
|
||||
citation-work
|
||||
to receive collected evidence items
|
||||
|
||||
evidence-source
|
||||
to access source metadata and document context
|
||||
|
||||
citation-evidence
|
||||
to integrate evidence-backed forms and structured workflows
|
||||
```
|
||||
|
||||
It should avoid direct dependency on viewer internals or document ingestion internals.
|
||||
|
||||
---
|
||||
|
||||
## First Useful Version
|
||||
|
||||
A first useful version of **evidence-binder** should provide:
|
||||
|
||||
* generic evidence target model,
|
||||
* evidence link model,
|
||||
* evidence set model,
|
||||
* relation type model,
|
||||
* target evidence state model,
|
||||
* simple in-memory binding service,
|
||||
* active target / active evidence state handling,
|
||||
* helper logic for linking evidence to form fields,
|
||||
* helper logic for listing evidence by target,
|
||||
* helper logic for switching active evidence,
|
||||
* initial visual guide state model.
|
||||
|
||||
The first version does not need a full form renderer, but it should make evidence-backed form workflows possible.
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
The repository is successful when another subsystem can use it to:
|
||||
|
||||
1. define a structured target such as a form field,
|
||||
2. attach one or more evidence items to that target,
|
||||
3. describe the relation between evidence and target,
|
||||
4. retrieve all evidence for the target,
|
||||
5. activate one evidence item,
|
||||
6. coordinate target, evidence card, and source annotation state,
|
||||
7. indicate whether the target has sufficient evidence.
|
||||
|
||||
A developer or coding agent should be able to understand from this repository how evidence becomes connected to structured work.
|
||||
|
||||
---
|
||||
|
||||
## Repository Character
|
||||
|
||||
This repository should be:
|
||||
|
||||
* relationship-focused,
|
||||
* target-neutral,
|
||||
* form-friendly but not form-limited,
|
||||
* explicit about evidence relations,
|
||||
* lightweight at first,
|
||||
* compatible with multiple UI shells,
|
||||
* useful for both human review and agentic inspection,
|
||||
* careful not to absorb document or anchoring responsibilities.
|
||||
|
||||
---
|
||||
|
||||
## Guiding Statement
|
||||
|
||||
**evidence-binder exists to connect cited evidence to the structured things it supports.**
|
||||
Reference in New Issue
Block a user