UHP governance and versioning

Governance structure and change process

UHP is maintained in the HarnessRouter repository under a maintainer-led, proposal-first model. The governance document defines four principles:

• Prose before code. A change starts as a description of the problem, not a pull request.
• Three artifacts move together. No change lands unless the specification, the reference implementation, and the conformance suite are updated in the same change.
• Compatibility is a feature. A change that breaks conformant clients requires a new version and a migration path, not a changelog note.
• The bar is a working implementation. A proposal is accepted because something runs it, not for elegance.

The written change process has four steps:

1. Propose. Open a UHP Enhancement Proposal (UEP) as a GitHub issue labelled uep, containing a Problem, a Proposal, a Compatibility assessment (what a current-version client experiences), and Alternatives considered.
2. Discuss. Maintainers respond within 10 working days with one of: accepted in principle, needs work, or declined with reasons. Declines are recorded so the same proposal is not re-litigated.
3. Implement. An accepted UEP ships as one pull request containing: updated specification chapter(s); updated schema/ OpenAPI + JSON Schema; the updated reference implementation; a conformance test that fails before the change and passes after; and a CHANGELOG.md entry. A PR missing any of these is not ready.
4. Release. Additive changes ship into the current version. Breaking changes accumulate into a new dated version (see below) with a migration note.

Roles named in the document are: Maintainers (merge rights; responsible for consistency across the three artifacts and for responding to UEPs), Contributors (anyone opening a UEP, PR, or issue), and Implementers (anyone shipping a UHP server or client). The document states that implementer feedback outranks theoretical elegance in design arguments. Problems are reported through labelled issues: spec-bug for specification defects (ambiguity, unimplementable rules, spec/suite disagreement) and ordinary issues for reference-implementation bugs; security vulnerabilities use private disclosure, not public issues.

Conformance claims and naming

A claim of the form "UHP 2026-08-11 conformant (class)" means the conformance suite passes at that class, and publishing the report alongside the claim is expected. The governance document states there is no certification body, no fee, and no logo programme — the suite is the authority, it lives in the repository, and anyone can run it against any server.

On naming: the canonical name is the Unified Harness Protocol (UHP), and its site is https://unifiedharnessprotocol.org. Apache-2.0 grants rights to the code and the specification under its terms, but does not grant rights to the protocol name; "Unified Harness Protocol" and "UHP" are marks of HarnessRouter. An implementation may call itself "UHP-compatible" or say it "implements UHP" only if it passes the conformance suite; non-conformant, partial, or modified-fork implementations must not use the name in a way that implies compatibility. Stating factually that a product "works with" or "connects to" UHP is fine. Trademark and compatibility-claim questions go to contact@harnessrouter.ai.

Date-based versioning

UHP versions are dates in YYYY-MM-DD form — the day the version was published. 2026-08-11 is the current version. The documents say dates were chosen deliberately over semantic versioning: a date claims only when the version was published, it sorts, and it makes an implementation's age obvious. A version number's "safe vs breaking" promise is only as good as the discipline assigning it, and is routinely broken in practice.

Within a published version the structure is immutable. A server MAY within a version: add optional request fields; add fields to response objects; add new event types; add new error codes with a vendor prefix; and relax a constraint (accept input it previously rejected). A server MUST NOT within a version: remove or rename a field; change the type or meaning of a field; add a required request field; remove an event type or error code; or tighten a constraint. Interpretation: anything in that second list forces a new version rather than an in-place edit.

Client and server rules written into the versioning document:

• Client MUST ignore unknown fields, unknown event types, and unknown output item types; and treat an unknown error code as its type (an unrecognised server_error is still retryable).
• Server MUST report the served version in the UHP-Version response header; reject an unsupported requested version with unsupported_protocol_version rather than serving a different one; support at least one full version at a time; and SHOULD support the previous version for at least six months after a new one is published.

Deprecation is staged: a field or endpoint is marked deprecated in the specification and the OpenAPI document with the reason and replacement; kept working for at least two published versions; and removed no earlier than the second version after the announcement. Nothing is removed without a working replacement having existed first.

The current version documents two known compromises, kept for compatibility and flagged for a future major version: mixed field casing (the task surface is snake_case, the harness object is camelCase); and session deletion living at /v1/traces/{id} (a path that predates the session vocabulary, specified as-is rather than renamed so existing clients keep working).

Conformance classes and the version relationship

The specification defines three conformance classes: Core, Extended, and Full. A dated version and a class together name a specific set of obligations. A claim therefore pairs both — for example "UHP 2026-08-11 conformant (Full)" means the Full-class suite passes against the 2026-08-11 version. Interpretation: the class is the scope of obligations at a point in time; the date is the contract revision. Raising a claim's class or citing a newer date changes which checks apply.

Artifacts that must stay synchronized

The governance principle is explicit: no change lands unless the specification, the reference implementation, and the conformance suite move together in the same change. The written implementation checklist expands this into the concrete set that must stay in lockstep when the standard evolves:

A specification sentence with nothing enforcing it is, in the documents' own words, "a wish" — which is why the suite and implementation travel with every change.

Documented vs interpretation

Related pages

Read the specification guide, conformance, architecture, the HTTP API map, the glossary, about this site, and primary sources.

Primary sources

• UHP GOVERNANCE.md (maintainer-led, proposal-first process, roles, conformance claims, naming)
• UHP VERSIONING.md (date scheme, within-version rules, deprecation, known compromises)
• UHP CHANGELOG.md (2026-08-11 first published version and what it defined)
• Unified Harness Protocol official site
• UHP protocol repository (specification, schema, conformance suite)