tegwick
0d95e6dbcf
Some checks failed
Test Suite / unit-tests (3.11) (push) Has been cancelled
Test Suite / unit-tests (3.12) (push) Has been cancelled
Test Suite / code-quality (push) Has been cancelled
Test Suite / security-scan (push) Has been cancelled
Test Suite / integration-tests (push) Has been cancelled
Test Suite / e2e-tests (push) Has been cancelled
Test Suite / performance-tests (push) Has been cancelled
Test Suite / test-summary (push) Has been cancelled
Replaces the stub (State Hub integration only) with full dev commands, module architecture overview, LLM config resolution chain, infospace conventions, and active roadmap pointers. Removes CLAUDE.custodian.md (superseded by the expanded CLAUDE.md). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
121 lines
5.6 KiB
Markdown
121 lines
5.6 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Custodian State Hub Integration
|
||
|
||
This project is tracked as the **markitect** domain in the Custodian State Hub.
|
||
Hub topic ID: `5571d954-0d30-4950-980d-7bcaaad8e3e2`
|
||
|
||
**Session start:** Call `get_domain_summary("markitect")` via the `state-hub` MCP tool.
|
||
If the hub is not reachable: `cd ~/the-custodian/state-hub && make api`
|
||
|
||
**Session end:** Call `add_progress_event()` with `topic_id` above, a `summary`, and `event_type` (`note` / `milestone` / `blocker`).
|
||
|
||
**Available state-hub MCP tools:** `get_state_summary`, `get_domain_summary`, `add_progress_event`, `create_workstream`, `create_task`, `update_task_status`, `record_decision`, `resolve_decision`.
|
||
|
||
If the hub API is unavailable, use `curl` against `http://127.0.0.1:8000/docs`.
|
||
|
||
---
|
||
|
||
## Development Commands
|
||
|
||
All commands assume the `markitect-venv` virtual environment is active (`source ~/.venvs/markitect-venv/bin/activate` or equivalent). The package is installed in editable mode.
|
||
|
||
```bash
|
||
# Run the core test suite
|
||
pytest
|
||
|
||
# Run a single test file
|
||
pytest tests/test_issue_17_batch_processing.py
|
||
|
||
# Run tests by marker
|
||
pytest -m unit
|
||
pytest -m "not slow"
|
||
|
||
# Run with coverage
|
||
pytest --cov=markitect
|
||
|
||
# Run only fast unit tests (TDD inner loop)
|
||
pytest tests/unit/
|
||
|
||
# CLI entry point
|
||
markitect --help
|
||
|
||
# Infospace subcommands (primary active development area)
|
||
markitect infospace --help
|
||
markitect infospace eval-summary --update-metrics
|
||
|
||
# LLM helper commands
|
||
markitect llm-helper "<question>"
|
||
markitect llm-catalog
|
||
markitect llm-check
|
||
markitect llm-default
|
||
markitect llm-preference
|
||
|
||
# Install / reinstall in dev mode
|
||
pip install -e ".[analysis]"
|
||
```
|
||
|
||
## Architecture
|
||
|
||
MarkiTect is a CLI-driven markdown engine that treats documents as structured, queryable information spaces. Entry point: `markitect/cli.py` → `main()` (Click group). All subcommand groups are registered at the bottom of `cli.py`.
|
||
|
||
### Core Modules (`markitect/`)
|
||
|
||
| Module | Purpose |
|
||
|--------|---------|
|
||
| `spaces/` | InformationSpace model — composability, events, history, transclusion, rendering, sync |
|
||
| `prompts/` | Prompt resolver, compiler, execution engine, quality gates, dependency graph, traceability |
|
||
| `llm/` | LLM adapter layer — 4 text providers + embedding adapter; 7-layer config resolution |
|
||
| `infospace/` | Infospace lifecycle — init, entity parsing, evaluation, composition, graph export |
|
||
| `analysis/` | Graph analysis (networkx) and FCA (Formal Concept Analysis, pure Python) |
|
||
| `schema*/` | Schema generation, validation, naming, refinement, metaschema |
|
||
| `core/` | Foundational parser, AST, serializer, workspace |
|
||
|
||
### LLM Configuration (`markitect/llm/`)
|
||
|
||
Resolution order (highest → lowest priority):
|
||
1. CLI flags (`--provider`, `--model`)
|
||
2. `MARKITECT_HELPER_MODEL` env var (model only)
|
||
3. User preference (`[llm.preference]` in `~/.config/markitect/config.toml`)
|
||
4. Directory preference (`[llm.preference]` in `.markitect.toml`)
|
||
5. Directory default (`[llm.default]` in `.markitect.toml`)
|
||
6. User default (`[llm.default]` in `~/.config/markitect/config.toml`)
|
||
7. Hardcoded fallback: `gemini/gemini-2.5-flash`
|
||
|
||
Canonical models: `markitect/llm/models.py` (`RunConfig`, `LLMResponse`) and `markitect/llm/adapter.py` (`LLMAdapter`). These are mirrored in the standalone `/home/worsch/llm-connect/` package (`llm_connect`), which is installed as a local path dependency. `markitect/prompts/execution/{models,llm_adapter}.py` are re-export shims for backward compatibility.
|
||
|
||
**Gotcha:** The `OPENROUTER_API_KEY` env var may hold a stale key — `unset OPENROUTER_API_KEY` before running LLM commands if you get auth errors. `claude-code` provider fails inside Claude Code sessions (nested session restriction).
|
||
|
||
### Infospace (`markitect/infospace/`)
|
||
|
||
An infospace is a directory-based collection of typed entities governed by an `infospace.yaml` config. Key files:
|
||
- `config.py` — config loading, `find_infospace_config()`, `DisciplineBinding`
|
||
- `entity_parser.py` — parse entity markdown files from `output/entities/<slug>.md`
|
||
- `evaluation.py` / `evaluation_io.py` — per-entity LLM evaluation (5 dimensions)
|
||
- `state.py` — `build_state()` aggregates entity + evaluation state
|
||
- `history.py` / `checks/` — viability tracking and collection-level checks
|
||
|
||
Slugs use **underscores** (e.g., `accumulation_of_stock`). Active example: `examples/infospace-with-history/` (988 entities).
|
||
|
||
### Layered Architecture
|
||
|
||
The project has a partially-implemented layered architecture separate from `markitect/`:
|
||
- `domain/` — domain models (issues, projects)
|
||
- `infrastructure/` — config, repositories, logging, connection management
|
||
- `application/` — application layer (mostly empty)
|
||
- `capabilities/` — pluggable capability packages (`issue-facade`, `release-management`, `testdrive-jsui`, `markitect-utils`, `markitect-content`, `kaizen-agentic`)
|
||
|
||
### Tests
|
||
|
||
Tests live in `tests/`. Many test files are named `test_issue_NNN_*.py` (TDD by issue). Layered tests follow `test_l{N}_*.py` naming. The `tests/unit/` subtree has the cleanest structure and covers `prompts/`, `spaces/`, `llm/`, `infospace/`, `analysis/`.
|
||
|
||
Pytest config is in `pytest.ini`. Relevant markers: `unit`, `integration`, `e2e`, `slow`, `performance`.
|
||
|
||
### Active Roadmap Files
|
||
|
||
- `roadmap/infospace-tooling/PLAN.md` — main infospace roadmap (S1 ✅ S2 ✅ S3 nearly done)
|
||
- `roadmap/infospace-s3-closeout/PLAN.md` — S3 close-out tasks (C.1–C.8)
|
||
- `roadmap/llm-shared-library/PLAN.md` — llm-connect extraction (S1+S2 done, S3 pending)
|