kontextual-engine/docs/knowledge-operations-roadmap.md

Knowledge Operations Roadmap

Date: 2026-05-05

This roadmap re-scopes kontextual-engine around the updated INTENT.md, Product Requirements Document V0.2, Functional Requirements Specification V0.2, and the research bundle under wiki/kontextual-engine_scope_research_md_bundle/.

Review Finding

The refreshed vision changes the center of gravity. The project is no longer best described as a persistence-oriented system layer that happens to support agents. It is a headless knowledge operations engine: stable asset identity, context, provenance, governed retrieval, traceable transformation, workflow, audit, export, and agent-safe operation are all first-order concerns.

The previous KONT-WP-0004: Durable Persistence Foundation captured a real gap, but it was too narrow. Durable storage is now one part of a broader asset registry, governance, lineage, audit, workflow, and export foundation.

Product Shape

The new source documents establish the engine as reusable backend capability for systems that need to operate heterogeneous information assets:

• files and folders,
• markdown and text repositories,
• office documents and PDFs,
• datasets and structured records,
• notes, policies, and project documentation,
• knowledge-base articles,
• generated AI outputs,
• operational documents and application-linked records.

The strongest implementation wedge is:

Ingest a heterogeneous project or organizational corpus, assign stable asset identities, extract metadata and structure, build contextual relationships, support governed retrieval, and produce traceable derived artifacts through API-accessible workflows.

Roadmap Principles

• Treat identity, provenance, permission checks, audit, and structured errors as P0 infrastructure, not enterprise-only additions.
• Use docs/architecture-blueprint.md as the implementation shape for domain core, application services, ports, adapters, persistence, retrieval, workflow, service APIs, and agent-safe operation.
• Separate source, normalized, and derived representations.
• Keep transformations traceable to inputs, versions, parameters, actor, policy, and output artifacts.
• Expose APIs before UI and keep UI/application concerns as consumers.
• Make agent operation explicit, bounded, permissioned, auditable, and review-gated where needed.
• Use adapters for markdown tooling, document extraction, AI providers, search, workflow engines, external policy systems, and storage backends.
• Treat markitect-tool as the Markdown-native adapter dependency described in docs/markitect-tool-reuse-boundary.md and docs/markitect-tool-integration-usecases.md, with contract tests guarding the expected parser, selector, operations, snapshot, and context-package behavior.

Workplan Set

Workplan	Role	Primary Coverage
KONT-WP-0004	Architecture rebase	Establish the blueprint, resolve open product/architecture decisions, and publish V0.2 traceability.
KONT-WP-0005	Asset registry core	Stable identity, source/normalized/derived forms, metadata, permissions, audit, durable state.
KONT-WP-0006	Ingestion core	Jobs, connectors, extractors, local files, markdown, PDFs, office docs, datasets, normalization.
KONT-WP-0007	Retrieval core	Query contracts, lexical search, filters, context graph retrieval, permission-aware results, snippets, KPIs.
KONT-WP-0008	Operations core	Traceable transformations, derived artifacts, workflow templates, jobs, retries, review gates, exceptions.
KONT-WP-0009	Service and agents	Versioned service API, actor context, authorization middleware, agent operation catalog, context packages.
KONT-WP-0010	Enterprise readiness	Observability, admin recovery, export packages, governance inspection, events, quality and performance signals.

Superseded Plan

The old persistence-only KONT-WP-0004 scope is superseded:

• Durable asset state moves into KONT-WP-0005.
• Workflow run persistence moves into KONT-WP-0008.
• Context package references and agent constraints move into KONT-WP-0009.
• Snapshot/export behavior moves into KONT-WP-0010.

The same State Hub workstream ID is retained for KONT-WP-0004, but its purpose is now the architecture rebase that makes the new implementation set coherent.

FRS Traceability

FRS Area	Workplans
FR-001 to FR-010 asset registry and persistence	KONT-WP-0004, KONT-WP-0005
FR-020 to FR-030 ingestion and normalization	KONT-WP-0004, KONT-WP-0006
FR-040 to FR-050 metadata, classification, context	KONT-WP-0004, KONT-WP-0005, KONT-WP-0007
FR-060 to FR-071 search, query, retrieval	KONT-WP-0004, KONT-WP-0007
FR-080 to FR-090 transformations and derived artifacts	KONT-WP-0004, KONT-WP-0008
FR-100 to FR-110 workflows and jobs	KONT-WP-0004, KONT-WP-0008
FR-120 to FR-132 permissions, governance, audit, lifecycle	KONT-WP-0004, KONT-WP-0005, KONT-WP-0010
FR-140 to FR-146 versioning and provenance	KONT-WP-0004, KONT-WP-0005, KONT-WP-0008
FR-160 to FR-169 agent-safe operation	KONT-WP-0004, KONT-WP-0009
FR-180 to FR-188 APIs, integration, extensibility	KONT-WP-0004, KONT-WP-0009, KONT-WP-0010
FR-200 to FR-207 observability and administration	KONT-WP-0008, KONT-WP-0010
FR-220 to FR-225 export and portability	KONT-WP-0010
FR-240 to FR-245 errors and correctness	KONT-WP-0005, KONT-WP-0009

Current Capability Reality

The existing code remains useful but now represents only an early contract slice. It has artifacts, collections, relationships, in-memory storage, ingestion adapters, query, workflow run manifests, relationship graph helpers, and context packages. It does not yet implement durable governed asset identity, multi-format document ingestion, permission-aware retrieval, service APIs, audit logs, transformation execution, export packages, or agent-safe operation gates.

That gap is exactly what the new workplan set is designed to close.