Stability
Halfhand is heading to 1.0.0. This document is the promise 1.0.0 makes and
every release after it keeps: what's frozen, what's allowed to grow, and what
has to go through a deprecation cycle instead of just changing. It formalizes
the "backward compatibility is a feature" rule from CLAUDE.md's v1.0.0
addendum.
Everything here applies from 1.0.0 onward. Before 1.0.0 (the current
0.1.x-beta series), the on-disk and JSON schemas may still move faster than
this policy allows — pin a beta version in CI rather than tracking latest
until 1.0.0 ships (see README.md).
(a) CLI: flags, subcommands, exit codes
Every documented subcommand, flag, and its current default behavior is stable. New subcommands and new flags are always additive — they may be added freely, never as a reason to change what an existing invocation does.
Removing a subcommand or flag, or changing what an existing flag combination does, requires a deprecation cycle: at least one minor release where the old behavior still works but prints a warning (via
hh_core::warn_deprecated, the standard one-line stderr format — seehh-core/src/deprecation.rs), before it can be removed in a later minor release. Halfhand does not do major-version-only removals within the CLI — a deprecation warning must have shipped first, full stop.Exit codes are part of the contract, tested by
hh/tests/cli_conformance.rs. The full per-command reference, includinghh run/hh mcp-proxypassing the wrapped command's code through and the known gaps, is `docs/exit-codes.md`):Code Meaning Where 0success every command on success 1generic error any other failure (including a refused irreversible action, e.g. hh redact/hh export --no-redactrefusing a non-interactive confirmation)2usage error clap's own flag/argument parsing (unknown flag, missing required arg) 3session not found any subcommand that resolves a session id/ lastargument and fails to4redaction/policy block hh scanexiting with findings — the one place this code is used today, so CI can gate onhh scan --allNew exit codes may be added for new commands; an existing code's meaning for an existing command never changes.
--helpoutput (bothhh --helpand everyhh <sub> --help) is snapshot-tested (hh/tests/cli_conformance.rs); wording may improve, but a documented flag or subcommand does not silently disappear from it.
(b) --json
schemais frozen at2for the 1.0 series. Seedocs/json.mdfor the full field-by-field reference and the diff fromschema:1.- Additive changes — a new field, a new possible value for an existing
field (e.g. a new
agent_kind), a newbodyshape for an event kind — do not bumpschema. They're documented indocs/json.mdas they land. A documented field is always present once schema2documents it (never conditionally omitted); consumers must ignore fields and enum values they don't recognize rather than error. - A field is never removed, renamed, or retyped within
schema:2. That kind of change ships as a newschemavalue with both shapes documented side by side indocs/json.md, gated behind a major version ofhh. hh-core::event::JSON_SCHEMA_VERSIONis the single constant every JSON-emitting call site readsschemafrom (session objects, event/step objects, and thedoctor/gc/stats/scan/exportobjects) — one counter for the whole family, not one per command.
(c) On-disk database
- Migrations are forward-only and applied automatically, idempotently, on
every
Store::open(hh-core/src/migrations.rs). There is no down-migration and none is planned. - Any
1.xrelease ofhhcan open and correctly read a database written by any earlier1.xrelease. A migration only ever adds (a table, a column, an index) — seehh-core/src/migrations.rs's own module doc: "the v1.0.0 addendum permits additive schema changes … without a deprecation cycle; a breaking change to an existing table must go through STABILITY.md's policy instead." No migration under this policy breaks that promise; if one ever needs to, it requires a major version ofhhand an explicit, documented migration path (e.g.hh export --bundleon the old version,hh importon the new one) — not a silent schema break. hh.dbremains directly queryable withsqlite3— that transparency isn't going away. But the SQL schema itself (table/column names, types, indexes) is not frozen the way--jsonis: migrations may still reshape it release to release. The supported programmatic interface is--jsonandhh exportbundles, not raw SQL — build tooling against those, and treat directhh.dbqueries as a debugging/ power-user affordance, not an API.
(d) MSRV
- The minimum supported Rust version is 1.88. It is stated once, in the
workspace
Cargo.toml(rust-version; the crates inherit it withrust-version.workspace = true), and every other document repeats that number. - It is the real floor, not an aspiration: the oldest toolchain that builds
the committed
Cargo.lock. CI'smsrvjob installs exactly the declared version and runscargo check --workspace --locked, so a dependency update that needs a newer compiler fails CI instead of silently raising the MSRV. - Raising the MSRV is a minor-version change. It only happens in a
minor release, never a patch release, and is called out in
CHANGELOG.md. A dependency update that would raise it is held back (or pinned withcargo update --precise) until a minor release.
(e) hh-core semver policy
hh-core's public Rust API (types, functions, trait, including theAdaptertrait new adapters implement) follows semver for real: additive changes are always fine; a breaking change to a1.xhh-corerequires a major version.- This is enforced in CI today, ahead of the crate ever being published:
.github/workflows/ci.yml'ssemver-checksjob runscargo semver-checks check-release -p hh-core --baseline-rev origin/main --release-type minoron every PR —--release-type minormeans "additions are fine, breakage is not," exactly this policy. The one standing exclusion (--exclude enum_marked_non_exhaustive) covers enums that predate the#[non_exhaustive]convention and were marked as a one-time cleanup, not a recurring allowance. - Growth-prone public types (
SessionRow,Config, the error enums,AgentKind, …) are#[non_exhaustive]specifically so a new field or variant stays additive under that check instead of registering as a break. New public types added after1.0.0should default to#[non_exhaustive]unless there's a specific reason a caller needs exhaustive matching or construction.
What this document does not cover
- The replay TUI's keybindings and rendered layout, and
hh export --html's page — these are user experience, not a machine-readable contract, and can keep improving without a deprecation cycle. hh.db's SQL schema shape (see (c) above) — deliberately not frozen.- Anything under
docs/adr/— architecture decisions, not compatibility promises.