kontextual-engine/workplans/KONT-WP-0004-knowledge-operations-architecture.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
KONT-WP-0004	workplan	Knowledge Operations Architecture Rebase	markitect	kontextual-engine	completed	codex	markitect	high	4	2026-05-05	2026-05-06	e177f2dc-a2a0-41a4-b5cd-82e8f9f12f34

KONT-WP-0004: Knowledge Operations Architecture Rebase

Purpose

Rebase the implementation roadmap around the V0.2 product vision: kontextual-engine as a headless knowledge operations engine for making heterogeneous information assets persistent, contextual, governed, retrievable, transformable, and agent-operable.

This workplan supersedes the earlier persistence-only interpretation of KONT-WP-0004. Durable persistence remains required, but it must be designed with asset identity, provenance, permissions, audit, transformation lineage, workflow state, exportability, and agent-safe operation from the start.

Outputs

• Updated scope and roadmap documentation.
• docs/architecture-blueprint.md as the architecture baseline for the V0.2 implementation sequence.
• docs/markitect-tool-reuse-boundary.md and docs/markitect-tool-integration-usecases.md as the explicit boundary between markdown syntax tooling and the engine runtime.
• docs/architecture-core-implementation.md as the first code-backed domain core implementation note.
• Architecture decision notes for the P0 capability baseline.
• Traceability from PRD/FRS V0.2 requirements to implementation workplans.
• Revised implementation sequence for KONT-WP-0005 through KONT-WP-0010.

markitect-tool Boundary Remark

The architecture work must treat markitect-tool as the Markdown-native syntax and operations dependency, not as a subsystem to copy into this repo. Architecture decisions should require adapter-only imports, public Markitect APIs, and integration contract tests for parser, selector, operation, snapshot, and context-package behavior.

A4.1 - Reconcile implementation baseline with V0.2 vision

id: KONT-WP-0004-T001
status: done
priority: high
state_hub_task_id: "6b665ab1-cc8e-473b-824a-d953b598bb72"

Review the current Python package against the V0.2 PRD/FRS and identify which existing contracts can remain, which must be renamed or expanded, and which are now out of date.

Acceptance:

• Current modules are mapped to V0.2 capability areas.
• In-memory artifacts, collections, relationships, query, workflows, and context packages are classified as reusable, replace, or defer.
• The old persistence-only roadmap is explicitly superseded.

A4.2 - Define canonical asset identity and representation model

id: KONT-WP-0004-T002
status: done
priority: high
state_hub_task_id: "eed4f0b5-9080-4c76-9ae6-841459edbab6"

Define stable knowledge asset identity, source references, source representations, normalized representations, derived artifacts, aliases, supersession, lifecycle state, and duplicate/re-ingestion semantics.

Acceptance:

• FR-001 through FR-010 have an implementation model.
• Source, normalized, and derived forms are distinct.
• Identity is independent of path, filename, backend, and representation.

A4.3 - Define actor permission policy and audit baseline

id: KONT-WP-0004-T003
status: done
priority: high
state_hub_task_id: "7f34e36f-4e9b-40ab-bbe9-afaee4553a9f"

Define the minimum actor, authorization context, policy check, sensitivity, lifecycle, review, fail-closed, and audit event model needed for P0.

Acceptance:

• Human, application, automation, service, and AI-agent actors are modeled.
• Permission-aware retrieval and transformation rules are specified.
• Audit records include actor, operation, target, outcome, correlation ID, and policy context where available.

A4.4 - Define provenance lineage versioning and derived artifact model

id: KONT-WP-0004-T004
status: done
priority: high
state_hub_task_id: "6d20a457-7246-4380-943f-c6d726506356"

Specify how source provenance, versions, content changes, metadata changes, relationship changes, transformation runs, and derived artifacts are linked.

Acceptance:

• FR-080 through FR-090 and FR-140 through FR-146 are mapped to data contracts.
• Derived artifacts can explain their source assets, parameters, actor, policy, run, and output identity.
• Restore, supersession, and re-run behavior is defined at contract level.

A4.5 - Define retrieval architecture and quality KPIs

id: KONT-WP-0004-T005
status: done
priority: high
state_hub_task_id: "e4e6f188-9ac3-4daf-9633-f11d812e50fa"

Define the first retrieval architecture: lexical search, filters, relationship retrieval, stable pagination, snippets, citations/source-grounding, permission checks, feedback, and KPIs.

Acceptance:

• FR-060 through FR-071 have an implementation path.
• MVP retrieval does not depend on vector search.
• Precision, zero-result rate, p95 latency, citation precision, and permission fidelity are named as measurable targets.

A4.6 - Define workflow job and operation execution architecture

id: KONT-WP-0004-T006
status: done
priority: high
state_hub_task_id: "d0a9e9d4-12eb-406b-b32c-5b45f931f18c"

Define job and workflow execution boundaries for ingestion, enrichment, validation, transformation, review, publication, archival, synchronization, export, retries, cancellation, and exception handling.

Acceptance:

• FR-020 through FR-030 and FR-100 through FR-110 have job-state semantics.
• Workflow templates, runs, steps, dependencies, retries, failures, and outputs are explicitly modeled.
• Embedded execution vs adapter-backed orchestration is decided for MVP.

A4.7 - Define agent-safe operation catalog and review gates

id: KONT-WP-0004-T007
status: done
priority: high
state_hub_task_id: "965738a5-9538-45f6-98bb-7987aba62904"

Define explicit agent operations for inspection, retrieval, metadata enrichment, classification, transformation, workflow invocation, review submission, dry runs, and bounded context packages.

Acceptance:

• FR-160 through FR-169 have API-level operation contracts.
• Agent operations cannot bypass permission, lifecycle, export, or review policy.
• Destructive or sensitive actions can be denied, dry-run, or routed to review.

A4.8 - Publish roadmap traceability and update scope docs

id: KONT-WP-0004-T008
status: done
priority: medium
state_hub_task_id: "ea7313ce-fb1f-49b1-b5da-66a036893a04"

Update repo-local docs so humans and agents can understand the new product shape and implementation sequence.

Acceptance:

• SCOPE.md reflects the V0.2 knowledge operations vision.
• docs/knowledge-operations-roadmap.md maps PRD/FRS areas to workplans.
• docs/architecture-blueprint.md defines the implementation shape and review checklist.
• Markitect dependency boundaries and use cases are linked from roadmap and scope materials where they affect implementation sequencing.
• README.md points to the new research and roadmap materials.

Definition Of Done

• Architecture docs clearly distinguish engine, application, connector, provider, and domain-package responsibilities.
• Architecture docs define domain core, application service, port, adapter, persistence, retrieval, workflow, policy, audit, service API, export, and agent-safe operation boundaries.
• Workplans KONT-WP-0005 through KONT-WP-0010 exist and are linked to State Hub.
• python3 -m pytest passes.
• State Hub consistency passes without using the push-capable fixer.