markitect-tool/docs/markitect-main-scope-assessment.md

# markitect-main Scope Assessment

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

## Summary

`markitect-main` already contains many capabilities that map to the new
syntax-layer scope, but they are embedded in a broader platform. The successor
repo should migrate behavior selectively and reimplement the public contract
cleanly.

`markitect-tool` should not become a trimmed copy of `markitect-main`. It
should become the stable contract layer that higher systems can depend on.

## In-Scope Candidates

| FRS area | markitect-main evidence | Recommendation |
| --- | --- | --- |
| FR-001/002 parsing and structure | `markitect/core/parser.py`, `markitect/parser.py`, `markitect/core/section_tree.py`, `markitect/frontmatter.py`, `markitect/matter_*` | Reimplement core parser facade around `markdown-it-py`; migrate tests/fixtures and behavior where deterministic. |
| FR-010/012 schema definition and validation | `markitect/schema/`, `schema_loader.py`, `schema_validator.py`, `schema_generator.py`, `metaschema.py`, `markitect/schemas/` | Migrate concepts and schema fixtures; simplify into provider-neutral schema package. |
| FR-020/022 transformation and composition | `markitect/explode_variants/`, `docs/composition-guide.md`, `docs/md-explode-command.md`, transclusion mentions in infospace/spaces modules | Reimplement as small document operation primitives; avoid bringing infospace lifecycle assumptions. |
| FR-030/031 query and extraction | `markitect/ast_service.py`, JSONPath usage, `markitect/query_paradigms/`, search docs | Reimplement query API over the new structured representation; keep JSONPath-like querying if it remains lightweight. |
| FR-040/041 templating/generation | `markitect/template/`, `draft_generator.py`, schema-guided generation docs | Migrate deterministic templating ideas; keep LLM hooks external. |
| FR-050/052 CLI and automation | `markitect/cli.py`, `batch_processor.py`, output formatting helpers | Reimplement CLI as `mkt` with composable subcommands and structured output. |
| FR-060/061 configuration | `config_manager.py`, `markitect/llm/toml_config.py`, `.markitect.toml` references | Keep project/user config pattern, but drop provider-specific LLM config from core. |
| FR-070/071 caching/incremental | `ast_cache.py`, `cache_service.py`, `performance_tracker.py` | Migrate cache strategy after parser contract stabilizes. |
| FR-080/081 structured errors | `exceptions.py`, `validation_error.py`, `production/error_handler.py` | Reimplement compact typed errors early, because CLI/API behavior depends on them. |

## Out-of-Scope for markitect-tool

These areas belong elsewhere or should remain legacy unless a higher-layer
consumer needs them through the new library contract:

- `markitect/infospace/` and `markitect/spaces/`: project-level knowledge lifecycle.
- `markitect/prompts/`, `markitect/helper/`, `markitect/llm/`: prompt execution and provider adapters, except optional integration hooks through `llm-connect`.
- `markitect/assets/`, `plugins/`, `templates/document.html`, JS UI files: rendering and asset management.
- `markitect/graphql/`, `storage/`, `database.py`: persistent service/data layer experiments.
- `markitect/finance/`, `profile/`, `legacy/`, `gitea`, `tddai`, `services/`, `tools/`: project operations and unrelated tooling.
- Domain schemas and infospace example content, unless copied as test fixtures for generic markdown/schema behavior.

## Migration Principles

1. Start from the PRD/FRS command/API contract, not from old module names.
2. Prefer deterministic behavior and structured outputs before LLM integration.
3. Migrate tests before code when the old behavior is clearly in scope.
4. Treat old code as reference material; do not preserve backward compatibility unless the new contract explicitly needs it.
5. Keep database, platform, and domain lifecycle concerns out of this repo.

## Practicality Reassessment

The first implementation slices intentionally rebuilt the clean parser and JSON
Schema spine. That is necessary but not sufficient. The legacy project already
showed that heading counts and raw structural schemas have limited practical
utility.

The successor should prioritize a document contract framework before going much
deeper into generic tooling. See `docs/practical-schema-framework-research.md`
and `workplans/MKTT-WP-0004-practical-contract-framework.md`.

## Initial Architecture Target

```text
markitect_tool/
  core/          parse, document model, frontmatter, serialization
  schema/        schema load/derive/validate/report
  ops/           transform, compose, include/transclude
  query/         selection/extraction over structured documents
  template/      deterministic rendering and generation primitives
  cache/         content fingerprints and incremental processing
  cli/           mkt command surface
  integrations/ optional adapters, including LLM hooks
```

The package name should be decided in the implementation workplan. The product
name is `markitect-tool`; the CLI alias is `mkt`.