# Demo harnesses

Use live examples to try a complete task, and scripted lab fixtures to inspect
specific runtime mechanisms without model credentials. Each folder contains a
spec, supporting assets, and instructions. Change `harness.yaml` through the
validated CLI; code, schemas, and data remain ordinary files.

The current checkout has **three active examples** in `harnesses/`. Older
examples and scripted labs now live in `tests/fixtures/harnesses/`; commands
using their old `harnesses/<name>` paths need updating. These are source-checkout
assets, not directories installed by the runtime wheel.

## Live examples

| Example | Task and checks | Capabilities to inspect |
|---|---|---|
| [ranked-retrieval](../harnesses/ranked-retrieval) | Search engineering records and return grounded ranked IDs; measure recall and ranking metrics | Enforced tool phases, deterministic search/verification, local evals, a research charter for vocabulary mismatch |
| [ticket-triage](../harnesses/ticket-triage) | Account for every open ticket exactly once, with legal category/priority values and a reason | MCP-only data access, parallel reads, validation against the source queue |
| [log-forensics](../harnesses/log-forensics) | Find facts in a log larger than the inline context | Allowlisted shell, optional OS confinement, spilled results and handles, version-scoped run recall |

Ticket triage checks completeness, known/open IDs, duplicates, legal labels,
and a nonempty reason. It does not establish that the chosen priority or
category is the best semantic judgment. Ranked retrieval's larger dataset
contains alternative phrasings to expose vocabulary gaps; it is an example to
measure, not a promise that a small model will always retrieve correctly.

Follow each folder's setup instructions, then validate and inspect before
spending model budget:

```bash
hiveloom validate harnesses/ranked-retrieval --json
hiveloom run harnesses/ranked-retrieval \
  --input-text 'Our service keeps running out of database connections.' \
  --dry-run --json
```

Ticket triage's dry-run starts its declared MCP server to discover tools.
The source [workbench showcase](/workbench#explore-populated-examples-from-source)
seeds these examples with real runs and history; it makes paid model calls.

## Scripted lab fixtures

These providers and directors are scripts, not general-purpose models. They
exercise real tools, validation, journals, and experiment decisions, but cannot
establish LLM task quality or model performance.

| Fixture | What it demonstrates |
|---|---|
| [routing-lab](../tests/fixtures/harnesses/routing-lab) | Playbooks change model/tool sets, a pinned plan, forks, and assessed evolution |
| [memory-lab](../tests/fixtures/harnesses/memory-lab) | Stored-result transforms, run-scoped notes, exports by handle, durable lessons applied through review |
| [signal-lab](../tests/fixtures/harnesses/signal-lab) | Failure location, reflection, a refuted change reverted and a confirmed change kept |
| [delegation-lab](../tests/fixtures/harnesses/delegation-lab) | Fitness-gated peer handoff, referrals, parent verification, and lineage |
| [research-lab](../tests/fixtures/harnesses/research-lab) | A bounded research program, candidate experiments, sealed confirmation, and an observed ceiling |

For example, after installing any dependencies listed in its README:

```bash
hiveloom validate tests/fixtures/harnesses/research-lab --json
hiveloom research init tests/fixtures/harnesses/research-lab \
  --name trial --charter tests/fixtures/harnesses/research-lab/research.yaml --json
hiveloom research run tests/fixtures/harnesses/research-lab --name trial --json
hiveloom research report tests/fixtures/harnesses/research-lab --name trial --json
```

A fresh copy avoids a program-name collision. Foreign code requires the normal
trust decision before loading; trust only fixtures you have reviewed.

## Other complete fixtures

| Fixture | What to inspect |
|---|---|
| [quickstart](../tests/fixtures/harnesses/quickstart) | No-tool execution, journal, version hash, guardrails, redaction, packaging and serving |
| [example-summarizer](../tests/fixtures/harnesses/example-summarizer) | Builtin tools, schema/code validators, retry feedback, and an on-demand house-style skill |
| [article-extractor](../tests/fixtures/harnesses/article-extractor) | Custom extraction tool, output hook, and validation against the fetched page |

These three use live providers. The [site quickstart](/quickstart) constructs a
smaller summarizer from scratch instead of depending on a fixture path.

## Verification and measured results

The repository's `scripts/package_e2e.py` builds and installs the wheel in a
clean environment and exercises the fixtures through the installed CLI,
including offline research. Tests verify runtime behavior without credentials
or network. Live measurements are separate; see [Evaluations](/evals) for the
results, sample sizes, and limitations.