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.

Detailed follow-up:

- `docs/markitect-tool-reuse-boundary.md`
- `docs/system-layer-extraction-inventory.md`
- `docs/system-layer-migration-backlog.md`

## 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

```text
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.