QLens Evolution Specification

The Evolution Specification defines the intended transition from a repository of validated Markdown objects into a durable Knowledge Evolution System. It is subordinate to the Foundation Book: implementation may change, but reality remains authoritative, understanding remains correctable, and history remains traceable.

Normative language

The terms MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are normative. A requirement is complete only when its acceptance criteria are demonstrably satisfied.

Scope

This family specifies ten coordinated improvements:

1. Research Space as the primary runtime boundary.
2. A graph-first engine over canonical research objects.
3. A generated object registry and durable indexes.
4. A query language for structural research questions.
5. Explicit reasoning chains and competing hypotheses.
6. NUR 2 as a graph-aware research interface.
7. Human-governed AI assistance.
8. A constrained plugin architecture.
9. Multi-format publishing from one canonical source.
10. A staged roadmap with compatibility gates.

Compatibility principle

Markdown, YAML front matter, stable OIDs, Git history, and the current object contracts remain canonical. Databases, caches, search indexes, and rendered views are derived and MUST be reproducible.

Specification map

Specification	Primary concern
SPEC-EVO-001	Research Space
SPEC-EVO-002	Graph Engine
SPEC-EVO-003	Object Registry
SPEC-EVO-004	Query Language
SPEC-EVO-005	Reasoning Engine
SPEC-EVO-006	NUR 2
SPEC-EVO-007	AI Assistant
SPEC-EVO-008	Plugin System
SPEC-EVO-009	Publishing
SPEC-EVO-010	Roadmap

Change control

Changes to this family MUST be recorded in repository history. A breaking change MUST identify affected contracts, migration requirements, and the earliest permitted release boundary.