kontextual-engine/docs/markitect-main-scope-assessment.md

markitect-main Scope Assessment For kontextual-engine

This assessment compares /home/worsch/markitect-main with the kontextual-engine PRD, FRS, and intent documents.

Summary

markitect-main contains the seed ideas for this repo, but they are mixed with syntax tooling, UI, plugins, provider adapters, finance, issue tracking, and project-specific utilities. kontextual-engine should migrate concepts and tests selectively, then reimplement the runtime contract as a headless service and programmatic API.

The most important inheritance is not old module structure. It is the concept of a durable infospace-like knowledge environment with typed artifacts, relationships, evaluation/composition workflows, and agent-operable context.

In-Scope Candidates

FRS area	markitect-main evidence	Recommendation
FR-001 to FR-004 knowledge persistence	infrastructure/repositories/, infrastructure/connection_manager.py, docs/WORKSPACE_AND_DATABASES.md, migrations under migrations/prompts/	Reimplement a storage abstraction early. Reuse lessons from filesystem/SQLite split, but do not inherit workspace-local assumptions blindly.
FR-010 to FR-011 organization and relationships	markitect/infospace/models.py, relation_models.py, relation_parser.py, graph_export.py, examples under examples/infospace-with-history/	Migrate vocabulary and relationship tests where generic. Keep domain-specific example content as fixtures only.
FR-020 to FR-021 ingestion and normalization	markitect/infospace/pipeline.py, entity_parser.py, classifier.py, packaging/proxy docs, asset/document managers	Define ingestion interfaces that call external format tools. Markdown-specific parsing should route through markitect-tool.
FR-030 to FR-031 query and retrieval	markitect/infospace/evaluate.py, evaluation_io.py, classification_io.py, search plugin docs	Reimplement query as service/programmatic contract over persisted artifacts, metadata, and relationships. Avoid CLI/search-plugin coupling.
FR-040 to FR-041 transformation and composition	markitect/infospace/composition.py, markitect/packaging/transclusion/, docs/composition-guide.md, prompt dependency resolution roadmap	Keep composition/workflow ideas. Delegate document-level transforms to markitect-tool; engine tracks operation state and derived artifacts.
FR-050 to FR-052 workflow orchestration	roadmap/prompt-dependency-resolution/, migrations/prompts/, quality tables, run manifests, batch processor	Reimplement workflow model around explicit runs, steps, dependencies, inputs, outputs, and structured errors.
FR-060 to FR-061 AI interaction/context	markitect/helper/knowledge.py, markitect/llm/, evaluation/classification modules	Preserve agent use cases and context needs. Use llm-connect for providers and keep prompts/workflow state auditable.
FR-070 to FR-071 external tooling	markitect/plugins/, capabilities architecture, pyproject.toml file dependencies	Build adapter boundaries, not embedded capability code. First adapter should likely target markitect-tool.
FR-080 to FR-091 API and errors	markitect/query_paradigms/, production error handling, GraphQL docs	Define stable Python API first, then service API. Structured errors should be part of the first implementation slice.

Out Of Scope For kontextual-engine

• markitect/core/, markitect/schema/, markitect/explode_variants/, and document transform primitives: move/reimplement in markitect-tool.
• src/*.js, testdrive-jsui, rendering plugins, static assets, browser integration: not headless engine scope.
• markitect/llm/* provider implementations: use llm-connect.
• markitect/finance/, issue_tracker/, profile/, tddai, Gitea tooling, and release-management helpers: unrelated product scope.
• Domain content from examples: useful as fixtures only when testing generic engine behavior.
• GraphQL as a default interface: old docs are evidence of API needs, not a commitment to GraphQL.

Migration Principles

1. Start from the kontextual-engine PRD/FRS, not legacy package names.
2. Migrate tests and fixtures before code when behavior is clearly in scope.
3. Treat legacy code as reference material unless a module is already isolated and aligned with the new runtime boundary.
4. Keep syntax, provider, UI, and domain layers outside this repo.
5. Make persistence and operation state explicit before adding AI workflows.
6. Prefer API/programmatic contracts first; CLI can be administrative later.

Initial Architecture Target

kontextual_engine/
  artifacts/      artifact model, metadata, lifecycle operations
  collections/    grouping, domain/collection membership, relationships
  storage/        repository interfaces and backends
  ingest/         format-agnostic ingestion adapters and normalization
  query/          retrieval over content, metadata, and relationships
  workflows/      runs, steps, dependencies, derived outputs
  context/        agent context assembly and operation surfaces
  integrations/   markitect-tool, llm-connect, storage adapters
  api/            programmatic and service-facing contracts

The first implementation workplan should validate this shape against migrated tests before committing to a framework or storage backend.