Skip to content

Governed Writes and Roadmap Commands

QLens 4.0 completes the local-first portions of roadmap Phases 5 and 6. Canonical YAML is still the authority. Proposed changes remain outside the canonical graph until a reviewer approves them.

Stage a structured proposal

The patch must name an object and provide set and/or unset operations.

qlens propose \
  "Clarify the research question" \
  '{"oid":"QST-000001","set":{"body":"What evidence would revise the current understanding?"}}'

List proposals:

qlens review list

Approve a proposal:

qlens review approve PRP-ABC12345 \
  --reviewer "Mamun" \
  --note "Evidence and wording checked"

Reject a proposal without deleting its audit record:

qlens review reject PRP-ABC12345 \
  --reviewer "Mamun" \
  --note "Insufficient evidence"

Approval performs four operations atomically:

  1. validates protected fields;
  2. applies the patch to a copy;
  3. validates the complete resulting object;
  4. writes the canonical object and a before/after transaction bundle.

Transaction bundles are stored under repository/history/<oid>/.

Graph analysis

Find a directed path:

qlens path MOD-000001 QST-000001

Show transitive impact if an object changes:

qlens impact EVD-000001 --depth 8

List graph orphans:

qlens orphans

Generate reports:

qlens report contradictions
qlens report hypotheses --question QST-000001
qlens report health

Publication exports

Export all canonical objects as deterministic JSON:

qlens export build/objects.json --format json

Export one Research Space as Markdown:

qlens export build/foundation.md \
  --format markdown \
  --space RSP-000001

Portable package verification

qlens pack build/foundation.qlens.zip --space RSP-000001
qlens pack-verify build/foundation.qlens.zip

A valid package must contain its manifest, schemas, contracts, generated registry, and selected canonical objects.

NUR governance views

Regenerate NUR after repository changes:

qlens build

NUR generates read-only pages for:

  • Research Spaces;
  • canonical objects and backlinks;
  • the knowledge graph;
  • the research timeline;
  • declared contradictions;
  • repository health and orphan objects.

These pages are derived. Editing them never changes canonical research.