v2.2.1

What's New

Gentle AI v2.2.1 is a correctness release for the review lifecycle shipped in v2.2.0. It closes the paths where a review could freeze a candidate correctly and then become impossible to finish: reviewer results that could not be consumed, captures that were refused before they could occupy their lens slot, and lineages that had no terminal state left to reach.

Nothing about the outcome-first workflow changes. Routing, the kill switch, optional SDD, and delivery authorization all behave exactly as they did in v2.2.0.

Changes

Reviewer Inspection and Candidate Transport

• Reviewers read the frozen candidate through Git, not through a payload: START now exposes the immutable base and candidate trees plus the changed-path manifest, and reviewers inspect them with read-only Git commands against those exact objects. The eager single-line base64 diff is retained only for negotiated v1 compatibility, where a large candidate could exceed a reviewer's read surface and strand the review. (#1689)
• Legacy v1 subjects are admitted by the identity they actually negotiated: admission compared frozen-context trees unconditionally, but the published v1 preimage blanks those fields on purpose to stay stable. Every review-integration/v1 capture therefore failed with binding_mismatch before it could consume its lens slot, leaving the collect loop re-offering the same slot until it gave up. Admission now binds v1 through the candidate diff digest and v2 through the frozen trees.
• Finalization stays bound to the frozen context it was opened against, and retired candidate artifact authority loads instead of failing closed.
• Git path queries are batched, removing the per-path subprocess fan-out on large candidates. (#1957)

Review Authority and Recovery

• Verification outcomes are bound to the authority that produced them, so a recorded outcome can no longer be read against a different lineage or revision. (#1924, #1920, #1772, #1663)
• A review whose lens plan can never finish now has a terminal state: when some lenses captured a result and at least one never could, review abandon --incomplete-inspection retires the lineage under its own maintainer authorization schema. It discards the review — it never approves it — and records the captured and uncaptured lenses in the audit proof. A fully captured plan is refused, because that review can finalize.
• Refusals name a runnable continuation: review abandon no longer refuses a held entry without saying where to go next.
• Guard population claims are ratcheted, so a guard that stops covering its stated population is reported rather than silently narrowing.
• Consent relay recovery is restored for the negotiated consent envelope.

Agent Integrations

• OpenCode routes generated reviews through STATUS, so the negotiated transition is the single source of the next operation rather than a locally assembled invocation.

Release and Tooling

• Publication requires a green CI run on the exact shipped commit. The release preflight reads the CI conclusion for the tagged SHA and refuses to publish when no run exists, when it is still in progress, or when it concluded anything other than success.
• The friction benchmark reports stale dead-end declarations instead of silently outranking them. dead_end is the corpus's most expensive claim — it asserts no continuation exists — so a declaration left behind after the gap closes is now surfaced with the reason it no longer applied.
• Two end-to-end persona assertions test the promise instead of a stale proxy: --persona custom and theme-only installs asserted that CLAUDE.md was absent, which stopped being a valid proxy once routing guidance began writing that file by design. Both now read the managed-section markers. These had been red on main since routing guidance landed, including on the v2.2.0 tag.
• The Windows test lane runs to completion for the first time: its job declared a 30-minute timeout around a 35-minute step, so every push to main was cancelled at exactly 30 minutes and no main commit had a green CI run since 2026-07-21 — including the one v2.2.0 shipped from. The full suite is now sharded across runners, with a guard asserting the shards tile every test name so a range cannot be edited into silently skipping tests.
• The Darwin release-blocker guard no longer reports present tests as missing: it checked the manifest with printf | grep -q under set -o pipefail, so when grep matched early enough to exit while printf still had output buffered, printf took SIGPIPE and the pipeline reported failure instead of the match. It surfaced only once the test listing outgrew the pipe buffer, which is why it appeared as the suite grew and struck seemingly arbitrary entries.

Validation

Restoring v1 admission alone returns 14 friction-benchmark journeys: the corpus goes from 46/60 to 60/60 with --axis all.

The 43-journey core corpus completes with no failed journey, no out-of-band block, and no dead end. Measured against v2.2.0, every friction dimension is unchanged — human prompts, manual tokens, commands to completion, blocks and all five block classes, recovery round trips, model runs, and Git subprocesses all show a delta of zero. The correctness fixes in this release cost the operator nothing.

Contributors

This release is maintenance work on the v2.2.0 line and carries no external contributions. Thanks to everyone who reported against v2.2.0 — the issues closed here came from that testing.

Upgrade

Homebrew:

brew upgrade gentle-ai && gentle-ai sync

Go 1.25.10+ on any supported platform, including Windows:

go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@v2.2.1
gentle-ai sync