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.