Build, test, and validate uze — and how the conformance lab proves harness behavior

Development

Build and test

cargo build --locked --bin uze                  # debug build
cargo test --workspace --no-fail-fast           # full workspace suite
cargo clippy --all-targets -- -D warnings       # CI gate
cargo fmt --check

make help lists every wrapper (make build, make test, make check, make coverage, make artifacts…). ci.yml is the source of truth for what gates a merge; treat make check as a close local proxy, not a guarantee of parity.

Coverage is enforced too:

cargo llvm-cov --workspace --summary-only \
  --fail-under-lines 68 --fail-under-regions 69 \
  -- --skip foreground_status_reports

Three tiers, three questions

Tier	Proves	Against
`tests/`	what the domain does	fake harnesses, deterministically
`journeys/`	what uze does, end to end	the real CLI and TUI in a disposable world
`conformance/`	what a vendor harness does	the real harness binary, offline

Integration suites live under tests/, one main.rs per domain (cli/, memory/, packages/, workspace/, lifecycle/, projection/, integrations/, acceptance/), with shared infrastructure — an isolated TestEnvironment, a FakeHarness, canonical fixtures — in crates/uze-testkit. tests/README.md documents the L0–L4 taxonomy and where a new test goes.

Some of those tests are the architecture itself: the layering rules, the vendor-neutrality of core/application/CLI, and the workspace's never-block-on-Git rule all fail as ordinary test failures when broken.

Product journeys

A journey performs a user's flow through the real CLI and the real TUI, then checks the machine it left behind — the filesystem, Git, the recorded task state, the process table. It never asks uze whether uze is happy, which is what catches "exited zero, reported the artifact, wrote nothing". Screen text is only ever a gate that a gesture landed, never an assertion.

python3 journeys/journey.py list journeys/suites              # what is proven, in order
python3 journeys/journey.py run  journeys/suites --tag gate   # what a pull request runs
python3 journeys/journey.py run  journeys/suites/04-workspace

Every run writes its evidence under journeys/.evidence/: per check, the question as written against the value found on the machine. journeys/README.md has the vocabulary and the rules that decide what a journey is.

Seeing what uze did

Every action opens a span, and the two processes that outlive the gesture that started them — the TUI and the terminal server — keep a journal without being asked. It is on by default, because the run worth reading is the one nobody expected to have to read:

~/.uze/cache/logs/uze.<date>.log         # the TUI
~/.uze/cache/logs/terminal.<date>.log    # the terminal server

Rolled daily, pruned to seven days and a 64 MB floor, under cache/ — deleting it costs nothing. UZE_LOG is both the switch and the filter for a command's own text:

UZE_LOG=info uze doctor              # spans and events on stderr
UZE_LOG=uze_git=debug uze status     # tracing_subscriber filter syntax
make observe                         # Jaeger 2 in Docker: UI :16686, OTLP :4318

The OTLP exporter is behind the telemetry cargo feature and is not in the release binaries. docs/observability.md is the full guide.

OpenSpec

Change proposals live under openspec/ — a spec-driven work log, with archived changes kept:

openspec validate --all --strict

Conformance Lab

Real-harness evidence never links into the deterministic suite. conformance/ runs the real harness binary against a synthetic world — a disposable Docker environment with a synthetic provider, zero internet, zero tokens — one vertical per supported harness:

python3 conformance/lab.py --harness claude      # or codex | opencode | antigravity
make lab-replay                                   # replay a recorded run

contract/ states what every harness must prove, in outcome terms, and names no vendor; harnesses/<vendor>/bindings.py says how that harness is driven and carries no assertion. A harness that cannot deliver part of a contract declares that through its bindings, with a reason the run records — never by omitting the check (ADR-043).

The lab is vendor-specific by design; the deterministic suite (cargo test) runs everywhere.

Distribution

install.sh at the repository root is the official Linux installer: it downloads the prebuilt binary for the machine from GitHub Releases, verifies its SHA-256 against SHASUMS256.txt, refuses on mismatch, and installs into $XDG_BIN_HOME or ~/.local/bin (ADR-034). make test-installer exercises it, and gates CI.

A release enters main through a pull request like anything else: the Release workflow bumps the version, regenerates CHANGELOG.md, renders the release notes into the PR body, and publishes the six tarballs (Linux gnu/musl, macOS), an SBOM and signed provenance on the merge. Versions come from one place — [workspace.package].version in the root Cargo.toml, inherited by every crate. docs/versioning.md is the full procedure.

Marketplace

This repository is itself the official uze marketplace: marketplace.json + plugins/** at the root, with plugins/uze — the uze:init, uze:worktree and uze:architect Skills — as the one official plugin.

Development

On this page