# Roadmap

Lens is now past the scaffold stage: it has adapters, deterministic retrieval,
portable context bundles, a CLI, a small HTTP route, tests, GitHub Pages, and
starter contributor issues. The next work should deepen reliability and make
Pulse integration more real.

It now also accepts exported human/agent interaction logs as read-only evidence,
without becoming an interaction store or agent runtime.

It accepts ActivityStreams exports as another read-only evidence source for
online human/agent interaction graphs. ActivityPub server behavior remains out
of scope.

It accepts already-resolved OriginTrail Knowledge Asset snapshots and preserves
UAL citations. OriginTrail DKG resolution, querying, publishing, and anchoring
remain out of scope for Lens.

It can inspect Pulse JSON-LD export shape and produce deterministic counts for
consumer compatibility. A real Pulse fixture generated by
`tools/generate_pulse_fixture.py` is checked in as data. Pulse remains
responsible for canonical verification, round-trips, mutation, transport, and
storage.

## Current Priorities

### 1. Pulse Contract Drift Checks

Keep the real Pulse fixture fresh as `Knitweb/pulse` evolves. The fixture should
remain generated by Pulse `export_web`, while Lens only consumes the committed
JSON and runs shape/adapter tests.

Implemented baseline:

- `tools/generate_pulse_fixture.py`;
- `tests/fixtures/pulse_real_web_export.json`;
- `lens inspect-pulse` and fixture contract tests.

Original issue: https://github.com/Knitweb/lens/issues/2

### 2. Adapter Ergonomics

Add examples for LightRAG, Neo4j-style rows, and vector-store results. Keep them
as static fixtures so no database is required in CI.

Related issue: https://github.com/Knitweb/lens/issues/1

### 3. Reliability Layer

Add deterministic, integer-only confidence, abstention, source-trust, and
citation-faithfulness checks. This is the first major quality layer before live
LLM adapters.

Implemented baseline:

- integer confidence report on every answer;
- abstention below the default confidence threshold;
- context replay preserves the same reliability behavior.
- offline JSON eval harness via `lens eval`.
- citation-faithfulness failures in eval reports.
- confidence-band calibration table with integer support rates.

Related issues:

- https://github.com/Knitweb/lens/issues/5
- https://github.com/Knitweb/lens/issues/6
- https://github.com/Knitweb/lens/issues/7
- https://github.com/Knitweb/lens/issues/8

### 4. Optional Live Model Boundary

Design optional live LLM adapters without changing the base dependency-free
package. Keep offline deterministic behavior as the default.

Related issue: https://github.com/Knitweb/lens/issues/4

### 5. Contributor Conversion

Make the Pages site and README show one copy-paste path for a new contributor:
clone, install, run tests, add fixture, submit PR.

Implemented baseline:

- GitHub Pages landing with runnable commands, compatibility matrix, boundaries,
  and contribution areas.

Original issue: https://github.com/Knitweb/lens/issues/3

## Merge Discipline

Small trusted merges are allowed under `docs/REVIEW_POLICY.md`, but reliability,
service boundary, package metadata, CI, and project-sync changes are control
surfaces and need maintainer review.

## Compatibility Discipline

Lens should keep improving as the best RLM interpretation layer over Knitweb,
OriginTrail-resolved data, and other online/p2p knowledge graphs. It should not
offer the same features as those systems. Use `docs/COMPATIBILITY.md` and
`lens capabilities` before adding features that touch storage, signing,
anchoring, p2p transport, accounting, or DKG publishing.