Development

Build and testCopy Anchor Link

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

Three tiers, three questionsCopy Anchor Link

Integration suites live under tests/, one main.rs per domain (acceptance/, architecture/, cli/, integrations/, lifecycle/, memory/, packages/, project/, projection/), 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 journeysCopy Anchor Link

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 didCopy Anchor Link

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.

OpenSpecCopy Anchor Link

Change proposals live under openspec/, a spec-driven work log, with archived changes kept. openspec validate --all --strict gates CI, and a warning fails it as an error would:

openspec validate --all --strict

Conformance LabCopy Anchor Link

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

In CI the Lab runs from conformance.yml, only when a change reaches what the Lab image reads, and every night. Each vertical runs as two legs (--part contract and --part vendor), and a leg that already passed against the same inputs is reused rather than run again. To reproduce one failure in seconds, python3 conformance/lab.py --sandbox <harness> opens the harness in the same world.

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.

PlaygroundCopy Anchor Link

The marketplace's example plugins (plugins/ beside the official one) can be tried against this checkout on your own machine, and playground/ holds disposable worlds to try the checkout as a person meets it:

make try                  # ~/uze-try: this checkout's uze installed, and a demo project with its examples
make pingpong-mcp         # the pingpong example's MCP server on PATH
make playground-linux     # a throwaway WSL distribution with this build installed
make playground-windows   # a fresh Windows Sandbox with this build installed (run from WSL)

DistributionCopy Anchor Link

install.sh at the repository root is the official Linux and macOS installer: it downloads the prebuilt binary for the machine from GitHub Releases, verifies the release key's signature over SHASUMS256.txt (with ssh-keygen) and the archive's SHA-256 against it, refuses when either fails, and installs into $XDG_BIN_HOME or ~/.local/bin (ADR-034). make test-installer exercises it, and gates CI. install.ps1 is its Windows counterpart, installing into %LOCALAPPDATA%\Programs\uze\bin and the user's Path; tests/scripts/installer.Tests.ps1 runs it under Windows PowerShell 5.1 and PowerShell 7 in the installer-windows job.

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), the two Windows zips with a Scoop manifest, 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.

MarketplaceCopy Anchor Link

This repository is itself the official uze marketplace: marketplace.json + plugins/** at the root, with plugins/uze (the uze:init, uze:rules, uze:worktree, uze:architect, uze:author and uze:try Skills) as the one official plugin, and beside it the examples (category example): the plugins a person browses to see what uze delivers, each checked by every_plugin_of_the_repositorys_marketplace_checks_clean.