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

Start from the PRD/FRS command/API contract, not from old module names.
Prefer deterministic behavior and structured outputs before LLM integration.
Migrate tests before code when the old behavior is clearly in scope.
Treat old code as reference material; do not preserve backward compatibility unless the new contract explicitly needs it.
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

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.

5.0 KiB Raw Blame History