docs/decisions/0005-prebuilt-rust-harness-cli.md

0005 Prebuilt Rust Harness CLI

Date: 2026-05-23

Status

Accepted, amended 2026-05-31, amended 2026-06-09

Context

The durable layer started as a thin shell wrapper around SQLite. That wrapper is now large enough to carry meaningful architecture risk: it mixes command parsing, SQL construction, migrations, import behavior, query rendering, and help text in one script.

The previous installer copied a shell wrapper into target repositories. That kept Harness easy to install, but it also meant a Rust rewrite was not only an implementation change. It changed the distribution contract for every project that receives Harness.

Decision

The future Rust implementation of the Harness CLI should be shipped as a prebuilt binary downloaded by the installer.

The command path for users and agents is the installed Rust binary:

scripts/bin/harness-cli <command>

On Windows, the repository-local binary is installed as:

.\scripts\bin\harness-cli.exe <command>

The installer should download, verify, and install the platform-specific Rust binary directly at that path. There should be no shell wrapper command contract.

The Rust CLI should follow the existing architecture rules:

• Domain: harness records, statuses, lanes, and value types.
• Application: use cases for intake, stories, decisions, backlog, traces, and queries.
• Infrastructure: SQLite repositories and schema migrations.
• Interface: command-line parsing, terminal output, and installer integration.

Release automation now follows the same distribution contract. After a PR is merged to main, the post-merge maintenance workflow updates CHANGELOG.md. When the merged PR changed the Rust CLI source, schema, Cargo metadata, or CLI release packaging, it also bumps the CLI patch version, updates the installer release tag pin, creates a harness-cli-v* tag, and invokes the reusable Harness CLI release workflow for that tag.

Alternatives Considered

1. Keep the shell CLI permanently. Rejected because the script has crossed from a thin wrapper into a growing application surface with weak testability.
2. Copy Rust source into every target project and build locally. Rejected because it makes Harness installation depend on a local Rust toolchain and increases setup friction for projects that only need the harness.
3. Require users to install a global harness binary separately. Rejected because Harness should remain repository-local for agents.
4. Download a prebuilt binary through the installer. Accepted because it keeps target repos simple while allowing the CLI internals to become typed, testable, and platform-aware.

Consequences

Positive:

• The durable-layer CLI can move to typed command parsing and tested use cases.
• Target projects do not need a Rust toolchain just to use Harness.
• The scripts/bin/harness-cli command is the stable entrypoint for agents on macOS/Linux; Windows uses the same repo-local path with the .exe suffix.
• Prebuilt releases can include a known SQLite linkage strategy.

Tradeoffs:

• The installer must learn platform detection and binary download behavior.
• Release artifacts need checksums or another integrity check.
• Unsupported platforms need a clear error path.
• The project needs a repeatable release process for supported platforms.

Follow-Up

• Implement the migration through US-002 Rust Harness CLI.
• Remove the old shell wrapper from installed project payloads.
• Add checksum verification for downloaded binaries.
• Treat the Rust CLI as the primary durable-layer implementation.