From 83a50a38d941e772775d05f5d9c81ccf3b2b0cb5 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 3 May 2026 20:43:12 +0200 Subject: [PATCH] State-hub connect and initial workplans --- .claude/rules/repo-boundary.md | 9 ++ .claude/rules/repo-identity.md | 9 ++ .claude/rules/session-protocol.md | 7 ++ .claude/rules/workplan-convention.md | 9 ++ CLAUDE.md | 61 +++++++++ README.md | 23 +++- docs/markitect-main-scope-assessment.md | 65 ++++++++++ docs/state-hub-integration.md | 50 ++++++++ workplans/MKTT-WP-0001-repo-foundation.md | 82 ++++++++++++ .../MKTT-WP-0002-markitect-main-migration.md | 87 +++++++++++++ ...KTT-WP-0003-core-toolkit-implementation.md | 117 ++++++++++++++++++ 11 files changed, 517 insertions(+), 2 deletions(-) create mode 100644 .claude/rules/repo-boundary.md create mode 100644 .claude/rules/repo-identity.md create mode 100644 .claude/rules/session-protocol.md create mode 100644 .claude/rules/workplan-convention.md create mode 100644 CLAUDE.md create mode 100644 docs/markitect-main-scope-assessment.md create mode 100644 docs/state-hub-integration.md create mode 100644 workplans/MKTT-WP-0001-repo-foundation.md create mode 100644 workplans/MKTT-WP-0002-markitect-main-migration.md create mode 100644 workplans/MKTT-WP-0003-core-toolkit-implementation.md diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md new file mode 100644 index 0000000..d777098 --- /dev/null +++ b/.claude/rules/repo-boundary.md @@ -0,0 +1,9 @@ +# Repo Boundary + +Keep `markitect-tool` focused on provider-neutral markdown primitives: +parse, validate, transform, compose, query, template, generate, configure, +cache, and expose through CLI/API. + +Leave infospace lifecycle, persistence/orchestration, project-specific +knowledge models, rendering applications, and service infrastructure to +higher-layer repositories. diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md new file mode 100644 index 0000000..7807de9 --- /dev/null +++ b/.claude/rules/repo-identity.md @@ -0,0 +1,9 @@ +# Repo Identity + +- Project: `markitect-tool` +- Domain: `markitect` +- Repo slug: `markitect-tool` +- State Hub topic ID: `5571d954-0d30-4950-980d-7bcaaad8e3e2` + +This repository is the markdown syntax/tooling successor to the in-scope core +of `markitect-main`. diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md new file mode 100644 index 0000000..8e30b86 --- /dev/null +++ b/.claude/rules/session-protocol.md @@ -0,0 +1,7 @@ +# Session Protocol + +1. Read `INTENT.md`, the PRD, the FRS, and active workplans. +2. Check State Hub for dispatch and blockers when available. +3. Treat workplan files as authoritative coordination state. +4. Record durable decisions in repository docs before reflecting them in State Hub. +5. Keep the implementation boundary narrow: syntax-layer toolkit, not platform. diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md new file mode 100644 index 0000000..bfa771b --- /dev/null +++ b/.claude/rules/workplan-convention.md @@ -0,0 +1,9 @@ +# Workplan Convention + +Workplans live at `workplans/-.md`. + +Use IDs with the `MKTT-WP-` prefix for this repository. Embedded tasks use +`MKTT-WP-XXXX-TNNN`. + +Each workplan should trace back to the PRD/FRS and indicate what is migrated, +reimplemented, deferred, or explicitly out of scope. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5b6bf7e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,61 @@ +# markitect-tool Agent Guide + +This repository is tracked in the Custodian State Hub as: + +- Domain: `markitect` +- Repo slug: `markitect-tool` +- Topic ID: `5571d954-0d30-4950-980d-7bcaaad8e3e2` + +At session start, orient from: + +1. `INTENT.md` +2. `wiki/ProductRequirementsDocument.md` +3. `wiki/FunctionalRequirementsSpecification.md` +4. `docs/markitect-main-scope-assessment.md` +5. Active files in `workplans/` + +## State Hub + +This repo is registered with State Hub through the local Custodian service. +State Hub is an index/cache for coordination state; the authoritative work +items live in this repository as Markdown workplans. + +Use State Hub to inspect current dispatch, blockers, progress, and cross-repo +coordination, but write durable plans and decisions into repository files first. + +## Boundary + +`markitect-tool` is the syntax-layer successor to the markdown-core parts of +`markitect-main`. It should stay CLI-first and library-always. + +It owns: + +- Markdown parsing and structured representation +- Schema definition, loading, derivation, validation, and reporting +- Markdown transformation, composition, and transclusion primitives +- Structured query and extraction over markdown documents and corpora +- Deterministic templating and optional LLM-assisted generation hooks +- Configuration, structured errors, caching, and incremental processing + +It does not own: + +- Infospace lifecycle, entity quality evaluation, or domain curation +- Persistent knowledge platform behavior or orchestration +- Provider-specific LLM adapters +- Asset management, rendering plugins, visual editing, finance, or project tooling +- GraphQL/database services except as external consumers of the library + +## Development Posture + +Prefer a clean reimplementation around the new PRD/FRS contract. Migrate +behavior and tests from `markitect-main` only when they fit the new boundary. +Avoid importing legacy platform assumptions just because the old code contains +useful names. + +## Workplans + +Workplans live in `workplans/` and follow the Custodian ADR-001 convention: + +- Frontmatter declares `type: workplan`, `domain: markitect`, and `owner: markitect-tool` +- Tasks are embedded as headed sections with fenced `task` blocks +- State Hub may index these files, but the files remain authoritative diff --git a/README.md b/README.md index fcd7b8f..43f8849 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,22 @@ -# repo-seed +# markitect-tool -A git repository template to bootstrap coulomb projects from. \ No newline at end of file +`markitect-tool` is a markdown-native toolkit and CLI for turning +semi-structured Markdown into structured, queryable, reusable knowledge +artifacts. + +This repository is the syntax-layer successor to the in-scope core of +`markitect-main`. Its product boundary is defined in `INTENT.md` and the +requirements documents in `wiki/`. + +## Start Here + +- `INTENT.md` - project purpose, boundaries, and design principles +- `wiki/ProductRequirementsDocument.md` - product scope and success criteria +- `wiki/FunctionalRequirementsSpecification.md` - observable functional behavior +- `docs/markitect-main-scope-assessment.md` - migration assessment from `markitect-main` +- `workplans/` - source-of-truth implementation and migration plans + +## State Hub + +The repo is registered with the Custodian State Hub as `markitect-tool` under +the `markitect` domain. See `docs/state-hub-integration.md`. diff --git a/docs/markitect-main-scope-assessment.md b/docs/markitect-main-scope-assessment.md new file mode 100644 index 0000000..a830f48 --- /dev/null +++ b/docs/markitect-main-scope-assessment.md @@ -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`. diff --git a/docs/state-hub-integration.md b/docs/state-hub-integration.md new file mode 100644 index 0000000..3009493 --- /dev/null +++ b/docs/state-hub-integration.md @@ -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` | diff --git a/workplans/MKTT-WP-0001-repo-foundation.md b/workplans/MKTT-WP-0001-repo-foundation.md new file mode 100644 index 0000000..d64ac07 --- /dev/null +++ b/workplans/MKTT-WP-0001-repo-foundation.md @@ -0,0 +1,82 @@ +--- +id: MKTT-WP-0001 +type: workplan +title: "markitect-tool Repository Foundation" +domain: markitect +status: active +owner: markitect-tool +topic_slug: markitect +created: "2026-05-03" +updated: "2026-05-03" +state_hub_workstream_id: "4d405d74-faec-440e-873e-692ff9ca96e7" +--- + +# MKTT-WP-0001: markitect-tool Repository Foundation + +## Purpose + +Establish this repository as the State Hub-connected successor workspace for +the in-scope core of `markitect-main`. + +## P1.1 - Integrate State Hub repository registration + +```task +id: MKTT-WP-0001-T001 +status: done +priority: high +state_hub_task_id: "34d2fba4-a03c-4d8f-a25c-b19a1c2f698d" +``` + +Register `markitect-tool` under the `markitect` domain, record the repo slug, +and preserve the integration details in repository documentation. + +## P1.2 - Add agent-facing repo rules + +```task +id: MKTT-WP-0001-T002 +status: done +priority: high +state_hub_task_id: "b19f88a0-850e-428e-8131-4c4af2cbfc42" +``` + +Create `CLAUDE.md` and `.claude/rules/` material so future sessions start from +the new PRD/FRS and the State Hub-backed workplan convention. + +## P1.3 - Establish workplan convention + +```task +id: MKTT-WP-0001-T003 +status: done +priority: high +state_hub_task_id: "4a770e4f-81b0-4f82-8f46-5886ee2fae36" +``` + +Create `workplans/` and seed source-of-truth workplans for foundation, +migration assessment, and implementation. + +## P1.4 - Add initial project packaging decision + +```task +id: MKTT-WP-0001-T004 +status: todo +priority: medium +state_hub_task_id: "c15f8492-93d0-43aa-ba12-0d4aaff97c03" +``` + +Choose package/module names, Python version target, dependency manager, and +test runner. Keep the decision lightweight and aligned with the future `mkt` +CLI entry point. + +## P1.5 - Add SBOM source once manifests exist + +```task +id: MKTT-WP-0001-T005 +status: blocked +priority: medium +state_hub_task_id: "e77a5e46-aaa2-4717-922f-a871fa2fd1cc" +``` + +After packaging files are introduced, generate or identify the SBOM source and +update State Hub registration metadata. + +Blocked because the repository has no implementation package manifest yet. diff --git a/workplans/MKTT-WP-0002-markitect-main-migration.md b/workplans/MKTT-WP-0002-markitect-main-migration.md new file mode 100644 index 0000000..335208a --- /dev/null +++ b/workplans/MKTT-WP-0002-markitect-main-migration.md @@ -0,0 +1,87 @@ +--- +id: MKTT-WP-0002 +type: workplan +title: "markitect-main Scope Extraction" +domain: markitect +status: active +owner: markitect-tool +topic_slug: markitect +created: "2026-05-03" +updated: "2026-05-03" +state_hub_workstream_id: "0fe54d2c-d579-4b03-a647-7a15bb835893" +--- + +# MKTT-WP-0002: markitect-main Scope Extraction + +## Purpose + +Inventory `markitect-main`, identify which behavior belongs in the new +syntax-layer toolkit, and prepare migration/reimplementation slices. + +## P2.1 - Complete first-pass scope assessment + +```task +id: MKTT-WP-0002-T001 +status: done +priority: high +state_hub_task_id: "950de9fd-7540-4e0f-bc4a-2fa86fc9fccc" +``` + +Compare the old repo against the new PRD/FRS and document candidate modules, +out-of-scope areas, and migration principles. + +## P2.2 - Extract reusable behavior test list + +```task +id: MKTT-WP-0002-T002 +status: todo +priority: high +state_hub_task_id: "994a8c17-bd13-476b-9b8e-86c50e1c4897" +``` + +Review `markitect-main/tests`, `testdata`, schema fixtures, and CLI integration +tests. Create a candidate test migration list organized by FRS section. + +Technical debt: `TD-MKTT-002`. + +## P2.3 - Map legacy commands to `mkt` + +```task +id: MKTT-WP-0002-T003 +status: todo +priority: high +state_hub_task_id: "f82b1f2c-887b-4378-b70b-84c1cb051742" +``` + +Inventory old `markitect` CLI commands and classify each as migrate, +reimplement, rename, defer, or out of scope for `mkt`. + +## P2.4 - Decide compatibility policy + +```task +id: MKTT-WP-0002-T004 +status: todo +priority: medium +state_hub_task_id: "56a12905-c3ec-42b0-893a-47ef023ea10a" +``` + +Define whether any old module paths, command names, file formats, or schema +names deserve compatibility shims in the successor. + +## Extension Points + +`EP-MKTT-002` tracks the query backend adapter boundary: keep the initial query +API small, but leave room for JSONPath-like or alternate selectors if they fit +the provider-neutral contract. + +## P2.5 - Identify external dependencies + +```task +id: MKTT-WP-0002-T005 +status: todo +priority: medium +state_hub_task_id: "4d51e763-bf5f-483b-8948-6306ff5a58bb" +``` + +Separate core dependencies from optional integrations. Initial candidates: +`markdown-it-py`, `PyYAML`, `jsonpath-ng`, and optional `llm-connect`. diff --git a/workplans/MKTT-WP-0003-core-toolkit-implementation.md b/workplans/MKTT-WP-0003-core-toolkit-implementation.md new file mode 100644 index 0000000..c771be6 --- /dev/null +++ b/workplans/MKTT-WP-0003-core-toolkit-implementation.md @@ -0,0 +1,117 @@ +--- +id: MKTT-WP-0003 +type: workplan +title: "Core Markdown Toolkit Implementation" +domain: markitect +status: active +owner: markitect-tool +topic_slug: markitect +created: "2026-05-03" +updated: "2026-05-03" +state_hub_workstream_id: "9fefb57d-985e-4125-8daf-03554844f45e" +--- + +# MKTT-WP-0003: Core Markdown Toolkit Implementation + +## Purpose + +Build the first usable `markitect-tool` implementation around the PRD/FRS +contract and the `mkt` CLI. + +## P3.1 - Bootstrap package and tests + +```task +id: MKTT-WP-0003-T001 +status: todo +priority: high +state_hub_task_id: "9d9501fe-6809-4b4f-bda6-ec5e5952ddc7" +``` + +Create project metadata, package layout, test structure, and a minimal CLI +entry point that can be installed or run locally. + +## P3.2 - Implement structured markdown parse contract + +```task +id: MKTT-WP-0003-T002 +status: todo +priority: high +state_hub_task_id: "7dead033-e249-46b0-9eb3-908ae231a987" +``` + +Implement FR-001 and FR-002: parse markdown files, preserve headings, +frontmatter, sections, and content blocks, and expose structured output via +API and CLI. + +## P3.3 - Implement schema load and validation + +```task +id: MKTT-WP-0003-T003 +status: todo +priority: high +state_hub_task_id: "36a22def-d415-4c08-a793-836ee52e4308" +``` + +Implement FR-010 through FR-012: define/derive schemas, validate documents, +and report structured violations with file/location context. + +## P3.4 - Implement query and extraction + +```task +id: MKTT-WP-0003-T004 +status: todo +priority: medium +state_hub_task_id: "e4f72218-601e-488f-a5df-171b91a747d2" +``` + +Implement FR-030 and FR-031 over the structured representation. Start with a +small query language or JSONPath-like adapter only if it remains simple. + +## P3.5 - Implement transform, compose, and include primitives + +```task +id: MKTT-WP-0003-T005 +status: todo +priority: medium +state_hub_task_id: "205d69eb-dd34-46a5-af0b-cc2de9d213d0" +``` + +Implement FR-020 through FR-022 as deterministic document operations. Keep +transclusion syntax and resolution rules explicit and testable. + +## P3.6 - Implement templating and generation hooks + +```task +id: MKTT-WP-0003-T006 +status: todo +priority: medium +state_hub_task_id: "307fa072-b1ce-42e8-9309-e2a92e130ae1" +``` + +Implement FR-040 through FR-042 with deterministic templates first and optional +LLM-assisted hooks supplied by external providers. + +Extension point: `EP-MKTT-001`. + +## P3.7 - Add caching and incremental processing + +```task +id: MKTT-WP-0003-T007 +status: todo +priority: low +state_hub_task_id: "236f90e3-1d79-473f-8c57-bcbbde9ece02" +``` + +Implement FR-070 and FR-071 after the parse/schema contracts are stable. + +## Known Technical Debt + +```task +id: MKTT-WP-0003-T008 +status: todo +priority: medium +state_hub_task_id: "94067c7e-e68b-45be-a1d6-90547eb15422" +``` + +Resolve `TD-MKTT-001` by adding the implementation scaffold: package metadata, +module layout, test runner, and `mkt` CLI entry point.