Use v4.1.1 for source installs. It is the same code with one consistent Go module checksum;
go install ...@v4.1.0fails checksum verification when it downloads from GitHub directly.
Gentle AI v4.1.0 is a minor release. Native review becomes proportionate: automatic review starts only for high-risk changes, the agent can choose which review lenses to run for what it touched, and an acknowledged passive delta is no longer offered again. The SDD retirement now also cleans up installed systems: Gentle-owned SDD agents, skills, commands, hooks, and profiles are removed on sync and install. OpenCode settings, plugins, launchers, and permissions are hardened, the Windows Full Suite is green again, and Gentle Shell installer candidates ship for Linux, Windows 11 x64, and macOS. The provider contract moves from 1.2.0 to 1.3.0, an additive minor bump for agent lens selection.
Provenance
- Previous stable:
v4.0.0→ff77164d4 - Release target:
v4.1.0→898d3976e8049a7238eaa7de60bff325c30d2b3d - Release workflow: run 38240234416
- Verification: preflight, release, and verify jobs all succeeded.
- Provider contract:
1.3.0(was1.2.0)
What's new
Proportionate, intent-aware native review
Native review now scales with what changed. review assess reports review_due: true only for high risk. A medium candidate reports review_due: false with under_budget, whatever its changed_lines, because size is a reviewer prompt budget, not risk. Review findings are graded with consistent severity and judged against the change's intent. START and the STATUS preflight accept --lenses <r,...> --lenses-reason <text>, so the agent can name the 4R lenses that fit what it touched instead of taking the tier default. A high candidate may run fewer than four lenses. The selection and its reason are frozen with the authority, recovery successors inherit them, and a resumed START on an active lineage keeps the frozen selection. Callers detect support through the new start_lens_selection capability. After a base-diff candidate is acknowledged, review detects the passive delta that follows and stops offering review for it, without hiding a review that is still live.
Included work: #5345 (issue #5344), #5348 (issue #5347), #5351 (issue #5350), #5322 (issue #4739).
ODD orchestration delegates for a reason
The orchestrator delegates when it has a named reason, not because a task is large. Work is delegated when understanding exceeds the inline evidence budget, when two or more independent writers have separate edit surfaces, or when a high-risk change needs an independent verifier. File count and task size alone never decide the route. Test discipline and the verify handoff now reach every runtime, and OpenCode verification uses probes derived from the spec and tests each requirement.
Included work: #5250 (issue #5249).
Gentle Shell installer candidates
gentle-ai shell install gains a TUI and an inspect-then-confirm command line for installing Gentle Shell. It supports a Separate mode on Linux amd64 (with a Shared mode for an existing owned Pi prefix) and on Windows 11 x64, and a user installer on macOS. These are candidates, not release-qualified paths. The Linux guide is marked "source candidate only, not a release guide", and the Windows guide states that real installation and terminal restoration remain unverified. The parent TUI now consumes a selection-only shell API.
Included work: #5242, #5279, #5407, #5445.
Opt-in install layouts
gentle-ai install --claude-orchestrator-modules is an opt-in pilot. It installs the global Claude Code orchestrator as a core prompt plus on-demand modules. It requires --scope global and the claude-code agent. Hosts that bundle their own tools can now choose an opt-in isolated install, and the Pi persona path follows the install scope.
Included work: #5313 (issue #5256), #5462 (issue #5461).
Breaking changes
- OpenCode external community plugins are retired. Gentle AI no longer offers installation of external community plugins or their TUI step, and the dead upgrade plumbing behind them is removed (#5200, issue #5199; #5317, issue #5316).
- Provider contract
1.2.0→1.3.0. This is an additive minor bump: it adds agent lens selection and the optionalstart_lens_selectioncapability. Review authority that carries a lens selection cannot be read by older binaries, so continue such a lineage with v4.1.0 or later (#5348). - Behavior changes that may affect scripts:
review assessno longer marksmediumcandidates as due; automatic review is forhighrisk only (#5351).installrejects component modifiers whose component is not selected, before any self-update (#5382).restorehonors explicit boolean flag values and the--terminator, and rejects extra targets (#5335).- The OpenCode orchestrator is restricted to Gentle AI subagents (#5403), and OpenCode permissions follow the Pi safety model (#5273).
The module path stays at /v4, and the review CLI changes are additive. Run gentle-ai sync after upgrading: installed orchestrator prompts, ODD guidance, permissions, reviewer assets, and SDD retirement cleanup all changed.
Upgrade now
brew upgrade gentle-ai
gentle-ai syncWindows and other source installs:
go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@v4.1.0
gentle-ai syncRun gentle-ai sync after upgrading so managed agent, reviewer, and runtime assets match the installed binary. This release removes retired SDD artifacts and refreshes orchestrator prompts and reviewer assets on sync.
What was fixed
Windows Full Suite is green on the release line
New Unix-only test assumptions and the elevated Windows Server runner had turned the Windows Full Suite red after v4.0.0: tests asserted POSIX modes, built executables without .exe, split quoted Windows paths with whitespace, and ran Gentle Shell ownership checks from an elevated process and an 8.3 temp path that the product refuses on purpose. The tests now model an unelevated account, the oversized cli-n-o shard is split, and the post-v4.0.0 follow-ups added the Windows npm stubs and fixed a flaky RDD writer test. Product checks are unchanged.
Included work: #5471 (issue #5470), #5187 (issue #5186), #5343 (issue #5336).
SDD retirement reaches installed systems
v4.0.0 removed SDD from the product, but Gentle-owned SDD artifacts stayed on users' disks, and on Pi the CodeGraph manifest brought retired SDD agents back. Sync and install now remove Gentle-owned native SDD agents. They also remove OpenCode and Kilocode SDD agents, SDD skills, commands, the Claude preflight hook, Codex SDD profiles, the Kimi SDD module, and stray SDD prompt blocks. Uninstall retires the SDD inventory and removes the Claude SDD workflow only where Gentle AI can prove it owns it. A runtime home that is a file is treated as holding no SDD prompt. User-facing TUI and CLI text no longer mention SDD, and installed guidance no longer references SDD or OpenSpec.
Included work: #5294 (issue #5253), #5295 (issue #5219), #5298, #5299, #5301, #5308, #5312, #5307, #5297, #5202 (issue #4994), #5319 (issue #5318), #5321 (issue #5320).
OpenCode settings, plugins, launchers, and permissions
OpenCode settings writers lost JSONC comments and could make partial mutations. Writers now keep JSONC through every routing step and check settings before changing anything. Managed plugin sync now matches install and trusts released bytes. Newer SDKs with the same major version are accepted, and SDK installs are pinned exactly. Every shipped plugin is retired with shared ownership across install, backup, and uninstall. A drifted managed plugin is scoped to its own agent. Released Kilocode plugin bytes are removed when the agent is fully removed. Managed launchers now have hardened ownership, stay stable across upgrades, and persist the POSIX PATH in login profiles. Slow version probes are allowed to finish. The Gentle logo check is skipped on OpenCode 2.x. Activation readiness is reported from the effective state. Orchestrator question access is restored, and delegated skills load by name. A user's deny-by-default is kept when the overlay merges. Configured catalog variants are merged, and effort variants are ranked. Dry-run reports the V2 SDK stop.
Included work: #5052, #5053, #5305, #5277 (issues #5099, #5185, #5192), #5278 (issues #5184, #5208), #5281, #5282 (issues #3453, #5238), #5303, #5309 (issue #4940), #5396 (issue #5393), #5275 (issue #3451), #5276 (issue #3452), #5338 (issue #5272), #5370 (issue #4796), #5085, #5293 (issues #4457, #4816), #5304, #5311 (issue #5310), #5273, #5403 (issue #5402), #5315.
Native review lifecycle and evidence
Committed corrections are now validated against HEAD even when the working tree has unrelated changes. An audited rejected-validator outcome can now close a review as terminal. A resumed START keeps the frozen lens selection. Frozen candidates now include dependency lockfile patches. Compact diagnostics for historical compatibility failures are preserved. The cross-lane battery is restored, and the review-acknowledged schema is published. The closure schema now carries targeted validator evidence. OpenCode relays get a sealed repository context that names its root, and review eligibility is resolved once per process. Role result shapes defer to the provider schema, and refusal causes are surfaced. Every review command declares its runtime, and STATUS renders agentless for Pi. rctx2 now returns granular error codes and skips dead registered worktrees. START refuses before granting authority when the frozen candidate context fails. Inspection preserves Linux Git directory metadata, and assigned Claude reviewer effort is honored.
Included work: #5454 (issue #4772), #5465 (issue #5428), #5406 (issue #5405), #5408 (issue #5292), #5388 (issue #5368), #5395, #4272 (issue #4223), #5300 (issues #4516, #5136), #5289 (issue #5058), #5288 (issue #5247), #5306, #5145 (issue #5143), #5096, #5144, #5339, #5360 (issue #4929).
Install, sync, and configuration preservation
Persona state must be unambiguous before sync changes anything. Managed merges keep exact JSON numbers and native TOML and YAML configuration. JSONC Claude settings survive hook install and removal. Claude hooks respect workspace scope. An explicit component selection wins over state that holds only metadata. Claude orchestrator assignments survive sync. Customized Context7 entries are preserved, and only the exact released defaults are migrated. Codex backups restore only from a validated CODEX_HOME. Installer progress completes after a rollback. Beta Engram setup requires Go before it applies.
Included work: #5237 (issue #1677), #5240 (issue #1672), #5243, #5302, #5342 (issue #5196), #5337 (issue #5140), #5382 (issue #2628), #5379 (issue #5204), #5426 (issue #4933), #5429, #5384 (issue #4509), #5335 (issue #2521), #2025 (issue #1885).
Doctor, updates, and self-upgrade
doctor reported tools as healthy without running them. It now runs a bounded execution probe, terminates the probe's process tree, and reports success only when the tool actually responds. It tells state access errors apart from invalid JSON, and it resolves managed agent config directories through each agent's adapter. Its sync remedy points at the executable that was invoked. Update checks keep successful results when only some checks fail, and a skipped check is no longer reported as an up-to-date tool. Source-build self-updates go through Go. Homebrew component formulas are trusted when the installed Homebrew supports it.
Included work: #5359 (issue #5127), #5376 (issue #4263), #5378 (issue #4262), #5387 (issue #4782), #5328 (issue #5323), #5366 (issue #4593), #5377 (issue #3479), #5357 (issue #4883).
Pi, Engram, CodeGraph, and other runtimes
Duplicate Engram declarations on Pi are prevented and repaired. Engram pins are preserved before package installation, and selected agent settings are snapshotted and restored. MCP servers blocked after the adapter migration are reported, and a verified pending CodeGraph status is preserved. CodeGraph CLI intelligence reads now require a fresh index. The explicit initialization workspace is preserved, and bare commands show local help. Engram resolves the project before a scoped search and validates stdout after an initialize write fails. Cursor activates managed rules with valid MDC frontmatter and installs the Judgment Day judges and fixer. Codex offers the efforts the runtime advertises and persists the service tier. GGA generates compatible test exclusion patterns. The persona keeps the human-selected reply language across harness turns. Telemetry serializes counter policy reads with state writes. The untracked selection schema uses an absolute ID.
Included work: #5353 (issue #5128) with stacked #5330, #5354, and #5355; #5381, #5383 (issue #5150), #5363 (issue #4813), #5341 (issue #4962), #5331 (issue #4245), #2022 (issue #1903), #5327 (issue #4172), #5329 (issue #5072), #5369 (issue #4934), #5296 (issue #2218), #5380 (issue #4189), #5365 (issue #5023), #5340, #5332 (issue #4821).
ODD handoffs and task sizing
Handoffs lost requirements because they paraphrased the user's spec. The feature document is now the verbatim spec that subagents read by reference. Verify runs the spec's example commands only when authorized and only on isolated state. Tasks are sized by understanding, risk, and resumability instead of file count.
Included work: #5215 (issue #5214), #5218 (issue #5217).
Test isolation, docs, and maintenance
Tests no longer inherit XDG configuration from the host. Output-assertion failures now show the captured output. New coverage proves Claude reviewer and subagent tool isolation, Pi routing preservation, OpenCode model profile persistence, and the Homebrew component command pipelines. The living docs, quickstart, CLI, telemetry, and contributor guides now match v4.0.0, and CI now catches drift in the agent and component inventories and any retired workflow terms. The issue taxonomy is aligned across its producers, and go.mod is tidy again so the release preflight passes.
Included work: #5314 (issue #5169), #5397 (issue #5375), #5385, #5430, #5439, #5386, #5367, #5362, #5414, #5191 (issue #5168), #5223 (issue #5221), #5236, #5239 (issue #5234), #5245 (issues #4428, #5244), #5261 (issues #3160, #3297, #3738, #3739, #5258), #5283 (issue #5258), #5207 (issue #5198), #5474 (issue #5473).
Numbers
356 non-merge commits, 121 merged pull requests, and 11 unique GitHub PR authors since v4.0.0. Three more pull requests were merged into the #5353 stack branch. Against v4.0.0 the release changes 851 files with 87,461 insertions and 7,393 deletions.
Install
brew install Gentleman-Programming/tap/gentle-aior
go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@v4.1.0Windows remains supported through the Go installation path, which needs Go 1.25.10 or newer. Official Windows binary archives and Scoop publication remain unavailable; Windows upgrades fail closed to Go-based guidance rather than downloading unsigned binaries. The scripts/install.sh and scripts/install.ps1 installers resolve the latest release tag and derive the /v4 module path from it.
Signed platform archives below: linux_amd64, linux_arm64, darwin_amd64, darwin_arm64, with checksums.txt and its minisign signature.
Full changelog: v4.0.0...v4.1.0