generated from coulomb/repo-seed
77 lines
5.0 KiB
Markdown
77 lines
5.0 KiB
Markdown
# 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`.
|