generated from coulomb/repo-seed
State-hub connect and initial workplans
This commit is contained in:
65
docs/markitect-main-scope-assessment.md
Normal file
65
docs/markitect-main-scope-assessment.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# 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.
|
||||
|
||||
## 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`.
|
||||
50
docs/state-hub-integration.md
Normal file
50
docs/state-hub-integration.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# State Hub Integration
|
||||
|
||||
`markitect-tool` was registered with the Custodian State Hub on 2026-05-03.
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Domain | `markitect` |
|
||||
| Repo slug | `markitect-tool` |
|
||||
| Topic ID | `5571d954-0d30-4950-980d-7bcaaad8e3e2` |
|
||||
| Local path | `/home/worsch/markitect-tool` |
|
||||
|
||||
## Integration Result
|
||||
|
||||
The registration workflow:
|
||||
|
||||
- Confirmed the State Hub API was reachable.
|
||||
- Confirmed the `state-hub` MCP server was configured.
|
||||
- Registered `markitect-tool` as a managed repo under the `markitect` domain.
|
||||
- Created the onboarding workstream `repo-integration-markitect-tool`.
|
||||
- Created four onboarding tasks for repo setup, workplans, SBOM, and catalogue hygiene.
|
||||
|
||||
## Repository Source of Truth
|
||||
|
||||
Per Custodian ADR-001, workplans and work items originate in repository files.
|
||||
State Hub should index and cache this state, not become the primary store.
|
||||
|
||||
The canonical workplan location is:
|
||||
|
||||
```text
|
||||
workplans/
|
||||
```
|
||||
|
||||
## Follow-Up
|
||||
|
||||
Once implementation dependencies exist, add an SBOM source and update State Hub
|
||||
with the SBOM ingestion result. This seed repo currently has no package manifest.
|
||||
|
||||
## Registered Extension Points
|
||||
|
||||
| ID | Title | Source |
|
||||
| --- | --- | --- |
|
||||
| `EP-MKTT-001` | Optional LLM-assisted generation adapter hook | `workplans/MKTT-WP-0003-core-toolkit-implementation.md` |
|
||||
| `EP-MKTT-002` | Query backend adapter boundary | `docs/markitect-main-scope-assessment.md` |
|
||||
|
||||
## Registered Technical Debt
|
||||
|
||||
| ID | Title | Source |
|
||||
| --- | --- | --- |
|
||||
| `TD-MKTT-001` | Implementation scaffold not yet created | `workplans/MKTT-WP-0003-core-toolkit-implementation.md` |
|
||||
| `TD-MKTT-002` | Legacy behavior requires test-level migration filter | `workplans/MKTT-WP-0002-markitect-main-migration.md` |
|
||||
Reference in New Issue
Block a user