docs: fold verification-run feedback into verify skill

Stale-compose-stack check + host-process path for branch code, worktree
.env/bun-install setup, concrete config.toml injection recipe, live-LLM
model-var requirement, and telemetry log-noise hint.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Aakash Kattelu 2026-08-03 18:05:22 -04:00
parent be3de9234e
commit 8e633ec1c3
1 changed files with 35 additions and 7 deletions

View File

@ -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
```