# 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)