Gentle AI v3.5.0 is a minor release whose headline is a default, not an API: receipt-driven development is now on by default. Every other change in this release is what that default needed to be safe to ship — the review lane's Windows test debt was paid down, the whole-state writers were serialized under the canonical lock, and the OpenCode provider-role capture learned to name typed refusal causes instead of reporting an opaque failure. Alongside it, gentle-ai sync now records when it last succeeded, and PR validation accepts strict non-closing issue references. The provider contract stays byte-frozen at 1.2.0, and the Go module path stays at /v3.
Provenance
- Previous stable:
v3.4.0→82a6de96ca6e1cb4f6bf603fe0c08ef1c2039833 - Release target:
v3.5.0→0b335e430546e8ca590c62d83722d745f18ef259 - Release workflow: run 35708011650
- Verification: preflight, release, and verify jobs all succeeded.
- Provider contract:
1.2.0
Release gate evidence on the exact tagged commit: CI run 35698925481 success, and Windows Full Suite run 35698925392 success across all ten shards. The Windows lane needed one gh run rerun --failed on the same commit to clear an intermittent telemetry lock failure that is unrelated to anything in this range and is tracked as #4874.
What's new
Receipt-driven development is on by default
The review switch that gates bounded native review of a candidate now ships enabled. Until v3.4.0 it was opt-in, so the default installation never ran a review and delivery followed ordinary repository policy without one. From v3.5.0 the effective mode is on unless a clone or a global setting says otherwise, and gentle-ai review mode status reports which source decided it.
This is a change of default, not of capability. The lifecycle is the same one that opt-in users already had: a candidate is frozen once, lenses are selected natively by risk tier, at most one bounded correction is permitted, and a terminal receipt is burned on acknowledgement. What changed is that a fresh install now gets it without asking. Turning it off is one command and remains the user's decision, never the agent's: gentle-ai review mode disable. The bench corpus and the docs were aligned with the default-on switch in the same change, and every journey now declares its review posture explicitly rather than inheriting the product default.
Included work: #4803.
gentle-ai sync records when it last succeeded
The persisted state now carries last_synced_at, written only after a sync completes successfully. A failed or interrupted sync leaves the previous value untouched, so the field answers the question operators actually ask: whether the managed assets on this host are current, and how stale they are.
Included work: #3906.
PR validation accepts strict non-closing issue references
pr-check now understands an issue reference that deliberately does not close the issue. Previously a PR either carried a closing keyword or failed the reference check, which forced contributors to write Closes #N on work that only advances an issue. The strict form lets a PR name its issue without claiming to finish it.
Included work: #4844 (issue #3352).
Breaking changes
No breaking changes are declared for v3.5.0. The Go module path stays at github.com/gentleman-programming/gentle-ai/v3, the provider contract remains byte-frozen at 1.2.0, and no review CLI flag changed shape.
Two behavior changes are named explicitly rather than left implicit:
- Receipt-driven development defaults to on. An installation that never enabled it will now run the review lifecycle on candidates. This is not an API break and no flag changed, but it changes what a default install does. Disable it with
gentle-ai review mode disable, or scope the decision to one clone with--scope clone.gentle-ai review mode statusis read-only and reports the deciding source and the effective mode. - Run
gentle-ai syncafter upgrading. Managed agent, reviewer, and runtime assets are versioned against the installed binary, and this release changes installed orchestrator instructions and reviewer assets. Without the sync, a v3.5.0 binary drives v3.4.0 assets.
Upgrade now
brew upgrade gentle-ai
gentle-ai syncWindows and other source installs:
go install github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai@v3.5.0
gentle-ai syncRun gentle-ai sync after upgrading so managed agent, reviewer, and runtime assets match the installed binary. If you want the pre-v3.5.0 review behavior, run gentle-ai review mode disable after the sync; gentle-ai review mode status confirms the effective mode and which setting decided it.
What was fixed
Whole-state writers now serialize under the canonical lock
Two independent paths could write the whole telemetry/app state concurrently and lose an update: the app's own state writers, and the sync/uninstall/TUI writers. Both now take the canonical state lock across their load-mutate-save sequence, so a writer cannot observe a stale state and overwrite a concurrent one. The Windows telemetry state lock still loses an update under contention in one guarded test; that path is tracked separately as #4874 and is not fixed here.
The Gentle Logo source is rolled back when its own registration fails
Installing the Gentle Logo plugin could leave the OpenCode source mutated after TUI registration failed, so a failed install still changed the host. Registration failure now rolls the source back, and the compensation covers the window where a write reports itself as landed and returns an error: both tui.json and the plugin source are compensated rather than trusting err != nil to mean nothing happened.
Included work: #4832 (issue #1678).
OpenCode provider-role capture names typed refusal causes
A provider-role capture that was refused reported an undifferentiated failure, which left the caller unable to tell a permission refusal from a transport error from a malformed envelope. The refusal now carries a typed cause, and an inconclusive classification is pinned by test so it cannot silently collapse back into the generic path.
Included work: #4835.
review assess fails closed and reports the v2 preflight failure
An error inside assess could produce output that a caller might read as a low-risk assessment. assess now emits a fail-closed envelope on error and uses the v2 preflight failure shape, so an unassessable candidate is verified like a high-risk one instead of being mistaken for a safe one.
Included work: #4822.
The runtime model catalog streams, and picker errors say what went wrong
Model discovery buffered the whole runtime catalog before the picker could render, and a catalog that ended exactly at the 16 MiB ceiling was rejected rather than accepted. Discovery now streams, the ceiling boundary is inclusive, and picker errors name their cause.
Included work: #4043 (issue #4042).
A custom agent keeps its own variant when an assignment carries no effort
The minimal overlay built for an existing custom agent unconditionally wrote "variant": assignment.Effort, which is the empty string when no effort is configured, and the deep merge then overwrote the user's own variant with it. The overlay now omits the key entirely on an empty effort, so the user's value survives; a non-empty effort still replaces it. Managed definitions keep clearing a stale variant on empty effort, and both halves are pinned by test so the rule cannot be weakened to "always omit".
Included work: #4078 (issue #3262).
The Unix binary is replaced atomically
An interrupted install could leave a truncated or half-written binary in place. The Unix install path now writes and renames, so the destination is either the old binary or the new one.
Included work: #3629 (issue #1728).
The Windows test lane stopped asserting things Windows cannot represent
Four Windows-only test defects had been keeping Windows Full Suite red on main across five consecutive heads, which blocked this release. Two asserted a restored file keeps mode 0600, which Go's os package cannot report on Windows because it does not implement Unix permission bits; those now compare against the mode recorded before the operation, so a restore that changes the mode still fails on every platform. Two left a helper executable running inside t.TempDir(), so Go's implicit cleanup hit Access is denied on a still-mapped image; the generated helper now records its grandchild's PID and a cleanup registered after the temp dir reaps it before removal. Separately, the V2 catalog harness stopped racing a fixed 30 ms sleep and now polls the condition it asserts under a bounded deadline.
Included work: #4852 (issue #4843), #4847 (issue #4846).
Stays open: #4874, the intermittent Windows telemetry state-lock lost update described above. No Windows Full Suite shard runs with -race, so that class is invisible to the race detector on the platform where it manifests.
Numbers
67 non-merge commits, 24 merged pull requests, and 6 unique GitHub PR authors since v3.4.0. By commit type the range is 28 fix, 18 test, 15 docs, 3 feat, and 3 ci: this release is mostly hardening and test-lane repair around one default change, which is the shape you want for a release that flips a switch on for everyone.
Install
brew install Gentleman-Programming/tap/gentle-aior
go install github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai@v3.5.0Windows remains supported through the Go installation path. Official Windows binary archives and Scoop publication remain unavailable; Windows upgrades fail closed to Go-based guidance rather than downloading unsigned binaries.
Signed platform archives below: linux_amd64, linux_arm64, darwin_amd64, darwin_arm64, with checksums.txt and its minisign signature.
Full changelog: v3.4.0...v3.5.0