diff --git a/.claude/skills/verify/SKILL.md b/.claude/skills/verify/SKILL.md index 994c5a96..0a83fa1a 100644 --- a/.claude/skills/verify/SKILL.md +++ b/.claude/skills/verify/SKILL.md @@ -14,23 +14,39 @@ run directly on the host (see Launch below); you'll need Postgres with pgvector and Redis reachable, plus a `.env` with connection strings and an LLM provider key for any flow that hits a model (deriver, dialectic, dreamer). +Working in a worktree? It carries neither `.env` nor `node_modules`. Copy +`.env` from the main checkout (that's where the provider keys live), and run +`bun install` in `sdks/typescript` if you'll run the full test suite — +otherwise the pre-push gate fails on a phantom `Cannot find package 'zod'`. + ## Launch -First check whether the stack is already running via Docker Compose — that's -the preferred setup, and reusing it beats starting a second one: +First check whether the stack is already running via Docker Compose: ```bash docker compose ps # look for api / deriver / database / redis docker compose up -d # start it if not ``` -Without Docker, run the two processes directly (shared Postgres + Redis): +A running stack is not the same as *your branch's code* running — check the +CREATED column; the images may be weeks old. For verifying a diff, the cheap +path is to reuse the stack's Postgres/Redis containers but run the branch's +API as a host process on a spare port: ```bash -uv run fastapi dev src/main.py # API server (default :8000) -uv run python -m src.deriver # deriver worker (queue consumer) +uv run uvicorn src.main:app --port 8901 # branch code, stack's DB/Redis +uv run python -m src.deriver # if the diff touches the worker ``` +This avoids both an image rebuild and the port/project-name conflicts a second +compose stack in a worktree would cause. Without Docker at all, run the two +processes the same way against host Postgres + Redis (API default port 8000 +via `uv run fastapi dev src/main.py`). + +When reading server logs, note that with the main `.env` the telemetry emitter +spams connection warnings at an unreachable endpoint — `grep -v +telemetry.emitter` before looking for the real error. + ## Drive it Prefer driving through the `honcho-cli` skill; fall back to the SDKs @@ -41,6 +57,10 @@ skill covers how to use the SDKs. When a change updates endpoints or makes schema changes, verify across all three surfaces — CLI, SDKs, and REST — since they can drift independently. +For LLM-path changes, the fastest synchronous surface is dialectic at the +`minimal` reasoning level: send a couple of messages, then hit +`/v3/.../peers/{peer_id}/chat` and observe the response. + ## Configuration Configuration is central to both driving the app and running tests: it's how @@ -52,6 +72,12 @@ process, and observe the behavioral difference at the surface — the same mechanism lets you point provider base URLs, model choices, and timeouts at credentials and proxies you actually have. +Two concrete levers: deep-nested settings (e.g. +`[dialectic.levels.minimal.model_config.overrides.provider_params]`) are +miserable as env vars — drop a partial `config.toml` in the repo root instead. +And for load-time config behavior, `uv run python -c "import src.config; ..."` +is faster than booting the server. + ## Test suites Three test types matter here. All run in CI, but they're also runnable locally @@ -69,7 +95,9 @@ uv run python -m tests.unified.run uv run python -m tests.unified.run --test-dir tests/unified/test_cases # Live LLM tests — real provider calls, for testing specific backends. -# Needs LLM_ANTHROPIC_API_KEY / LLM_OPENAI_API_KEY / LLM_GEMINI_API_KEY and -# LIVE_LLM_*_MODELS env vars; see tests/live_llm/README.md. +# Needs provider API keys AND model vars — without LIVE_LLM_*_MODELS the +# tests silently deselect that provider. See tests/live_llm/README.md. +export LLM_ANTHROPIC_API_KEY=... +export LIVE_LLM_ANTHROPIC_45_PLUS_MODELS=claude-sonnet-4-5 uv run pytest tests/live_llm -n 0 --live-llm --no-header -q ```