Gentle AI v4.0.0 is a major release: Organic Driven Development (ODD) becomes the only development workflow as SDD and OpenSpec retire, the Go module path moves to /v4, OpenCode V2 gains managed plugins and native review, Pi switches to its built-in MCP support, and the Windows Full Suite is green again. The provider contract remains at 1.2.0.
Provenance
- Previous stable:
v3.7.0→6dee8f833aec9e46015759c5065a9035795d9af1 - Release target:
v4.0.0→ff77164d4f56f1665b22fb6fac51c2ccbb769400 - Release workflow: run 36919433994
- Verification: preflight, release, and verify jobs all succeeded.
- Provider contract:
1.2.0
Release gate evidence on the exact tagged commit: CI run 36913345728 success, and Windows Full Suite run 36913345723 success across all ten shards. The Windows lane needed one gh run rerun --failed on the same commit to clear an intermittent lock-timeout failure in TestCloneLocalRDDOverrideConcurrentWritersKeepOneWinner that is unrelated to this range.
v3.7.0 is not an ancestor of v4.0.0: main carries patch-equivalent replays of the v3 line, including its own merge of #4912 at 204ccbd4, whose tree matches v3.7.0 except for seven repository-local .engram/ files. No history was rewritten.
What's new
ODD is the only development workflow
SDD and OpenSpec are retired and ODD is the single development route; independent native review (RDD) and test-first development stay available. Persisted SDD keys and user-owned installed files are preserved, and legacy uninstall removes only provably owned assets. Test-first guidance is installed by default, so strict TDD is no longer a separate choice. Every non-Pi runtime gets a managed orchestrator prompt from one shared contract, and delegation follows an evidence budget instead of file counts: work stays inline only when its evidence fits one parallel batch (at most 3 calls, about 10k tokens); otherwise one explorer returns a bounded path:line handoff. The generic orchestrator render (VS Code Copilot, OpenClaw, Trae) installs one model variant instead of both.
Included work: #4967 (issue #4959), #4978 (issue #4977), #5005, #5147 (issue #5139).
Go module path /v4 and version-aware installs
The module path is now github.com/gentleman-programming/gentle-ai/v4. The updater derives /vN from the version it installs instead of the running binary's major. Beta upgrades that cross a major pin both the module path and go install to the same checked commit. The Unix installer reads go.mod at the resolved release tag (stable) or main commit (beta) and installs that exact ref instead of @latest. The Windows installer's stable channel resolves the latest release tag and derives the module major from it, failing closed when the lookup fails. GoReleaser's trust-anchor linker path and the release-policy checks moved to /v4. Protocol identities and historical fixtures did not move.
Included work: #5081 (issue #5078), #4925 and #4926 (issue #4687), #4979 (issue #4687), #4965 (issue #4689).
OpenCode V2: plugins, SDK provisioning, partial sync, and native review
V2 models are discovered through the OpenCode API, which replaces the removed opencode models --verbose flag. V2 hosts get V2 plugin assets built on @opencode/plugin. Plugin writes are refused without the pinned SDK. For a fresh V2 config, Gentle AI can provision SDK 2.0.4 after a separate TUI consent, in an isolated npm environment that never reuses user or project credentials. Existing npm or Bun dependency state gets a manual command instead. If opencode --version cannot be detected, sync applies every other agent, reports Agents skipped: opencode, and exits non-zero. Native review is admitted on V2 only when a detected V2 runtime is paired with the exact managed relay declaration. Each review Task must run under the agent bound to its role, and refusals return one bounded reason code.
Compatibility limits, as documented in docs/opencode-compatibility.md:
- V2 review is proven on OpenCode 2.0.19 on macOS, with a scripted loopback provider. It is not proven with real reviewer models, other V2 releases, or other operating systems.
- Gentle AI manages only its own four V2 plugin assets: telemetry, model catalog, skill registry, and review transport. Existing user-owned incompatible assets are preserved.
- Community TUI plugin installation refuses on V2, and the Gentle logo is skipped because V2 has no equivalent slot.
- When the review plugin refuses a Task, OpenCode 2.0.19 skips later plugins' hooks for that call. Other plugins must not rely on observing refused review Tasks.
- Known fail-closed follow-ups remain open. A refusal reason can be lost when the relay exits before reading stdin.
authority_unavailableis reported asstale_authorityeven for lock or IO causes.--dry-rundoes not probe OpenCode.
Included work: #5115 (issues #4729, #4848, #4592).
Pi uses its built-in MCP support
Pi 0.99.0 and later read <Pi agent dir>/mcp.json through built-in MCP, but an installed /mcp extension such as pi-mcp-adapter replaces that support. Gentle AI therefore stops provisioning pi-mcp-adapter and retires it from existing installs. Sync migrates servers from a sibling mcp-adapter.json into mcp.json: existing entries win, other keys are preserved, and mcp-adapter.json is left untouched. Engram on Pi is native-only through gentle-engram, so Gentle AI never adds or removes an engram MCP entry there. Post-sync verification and doctor no longer expect one. Gentle AI does not check the Pi version itself, so hosts older than Pi 0.99.0 lose MCP servers until Pi is upgraded.
Included work: #5121 (issue #5067), #5132 (issue #5103), #5135 (issue #5134).
Workspace-scoped sync
gentle-ai sync --scope=workspace refreshes workspace-managed files without changing global configuration, state, backups, telemetry, plugins, or home-level hooks. The default scope stays global. Global-only components are skipped with explicit manual actions instead of leaking writes.
Included work: #5080 (issue #1074), #5109 (issue #5086).
Native review recovery from STATUS
Negotiated STATUS now returns a runnable native recovery command: predecessor lineage, expected revision, successor lineage and disposition, and the exact target selectors. Callers no longer author actor, reason, or authorization for this route. A successor keeps its predecessor's frozen policy and lens set. Shape overrides that conflict with the predecessor, and wrong or partial explicit authorization, fail closed. An unchanged candidate with failed criteria stops instead of retrying recovery. Core review authority is reused, not modified.
Included work: #5146, #5148 (merged into its stack branch), and #5151 (issue #1658).
Smaller additions
Codex presets (low-cost, recommended, powerful) and the curated Codex model catalog now recommend gpt-6.1-{astra,sol,luna} (#5154, issue #5153). Conductor is supported as a thin workspace orchestrator: it is detected from ~/.conductor and inherits Claude Code configuration without Conductor-specific managed files (#5060, issue #730). Kimi prefers the current ~/.kimi-code root and falls back to ~/.kimi (#5063, issue #782). review assess now judges added lines instead of unchanged source when it classifies risk (#4971, issue #4970). Telemetry reports knowable effort and classifies Claude Code built-in subagents (#5050, issue #5047). A managed-assets manifest model lays groundwork for detecting mixed binary and asset versions in doctor (#4760, issue #1884). Issue and PR skill guidance now ties authority to evidence (#4983, issue #4981).
Included work: #5154, #5060, #5063, #4971, #5050, #4760, #4983.
Breaking changes
- Go module path. The module is now
github.com/gentleman-programming/gentle-ai/v4. Everygo installand import must use/v4(#5081). - v3 self-upgrade cannot reach v4 on Go-based installs. The v3.7.0 updater hardcodes
.../gentle-ai/v3/cmd/gentle-aiand installs@v<latest>, which Go rejects for a v4 tag. Windows and othergo installusers must install v4.0.0 manually with the command under "Upgrade now". Homebrew users are not affected. This is based on reading the v3.7.0 source; a live run was not observed. - SDD and OpenSpec are removed (#4967):
/sdd-*commands, SDD profiles and phases, and OpenSpec workflow integration are no longer offered.- These subcommands are removed:
sdd-status,sdd-continue,sdd-attempt,sdd-archive-compose,sdd-task-result, andsdd-preflight-hook. install --sdd-mode,sync --sdd-mode, andsync --sdd-profile-strategyare removed.- User-owned installed files and persisted SDD keys are preserved.
- Strict TDD is no longer a separate option (#4978). The installer selection screen is removed.
sync --strict-tddis rejected with an error asking you to rerun without it. A savedstrict_tddno longer enables anything. - Review-driven prompts are scoped to runtimes with native review transport (#5005). RDD guidance now ships only to Claude Code, Codex, and OpenCode (Pi's prompt is owned by Gentle Shell). Every other runtime gets ODD-only prompts.
pi-mcp-adapteris retired (#5121, #5132). Sync removes it from existing installs, and Pi MCP servers now depend on Pi 0.99.0 or later built-in MCP.- Behavior changes that may affect scripts:
syncexits non-zero when it skips OpenCode because the version cannot be detected (#5115).- Antigravity registers Engram through its plugin configuration instead of the shared MCP configuration, and the old managed entry is removed (#5065).
- In workspace scope, OpenCode Engram, Context7, and Persona writers target the settings file OpenCode actually loads, not a stranded
<workspace>/.config/opencode/opencode.json(#5016).
The provider contract remains byte-frozen at 1.2.0. Run gentle-ai sync after upgrading: installed orchestrator prompts, routing guidance, and managed assets 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.0.0
gentle-ai syncRun gentle-ai sync after upgrading so managed agent, reviewer, and runtime assets match the installed binary. This sync replaces SDD guidance with ODD orchestrator prompts and retires pi-mcp-adapter on Pi hosts. On OpenCode V2 it also installs the V2 plugin assets. Upgrade Pi to 0.99.0 or later before syncing if you rely on Pi MCP servers. On v3.x Go installs, gentle-ai upgrade cannot cross to v4; use the go install command above once.
What was fixed
Windows Full Suite is green again
The Windows Full Suite had been red on main because of Unix-only test assumptions about quoting, mode bits, and path separators. One failure was a real product bug: the printed review recover continuation left --cwd unquoted, which breaks paths with spaces. The tests now keep portable assertions, and the continuation quotes --cwd. One Windows coverage gap remains: the TestV2SDK* tests are skipped on Windows until .cmd stubs exist.
Included work: #5174 (issue #5170), #5076 (issue #5074).
OpenCode and Kilo agents, settings, and uninstall
The SDD retirement removed the overlay that owned every managed OpenCode and Kilo agent, so Judgment Day agents and review lenses disappeared. Parity is restored. A JSONC-aware cleanup removes the legacy __managed_by marker that strict providers rejected. Theme, Persona, permissions, Context7, and Engram writers now use the effective settings file OpenCode loads. Kilo review cleanup removes only entries this run proved it owned. Uninstall now removes every managed OpenCode and Kilo agent, not only gentleman. The OpenCode review plugin checks the PATH gentle-ai version before relaying and refuses on binary skew.
Included work: #4998 (issues #4471, #4684, #4758), #5004 (issue #4471), #5006, #5008, #5016 (issue #5013), #5028 (issue #5025), #3731 (issue #3049).
Install and sync converge, and files keep their permissions
sync applied components in stored selection order, so the persona overwrote the Engram protocol on seven runtimes. Codex config.toml tables also shifted on every run. Install followed by sync now produces the same files. WriteFileAtomic used to apply 0644 when replacing an existing file, which made private 0600 configs world-readable. It now keeps existing permission bits, and mode-only changes are reported. TOML edits no longer treat a [section] line inside a multiline string as a real table, which could write into or delete user data. The Codex persona is wrapped in a managed marker.
Included work: #5017, #5014, #5019, #5024 (issue #5022), #5027 (issue #5026), #5069 (issue #981).
Review lifecycle
An escalated lineage was offered again as a fresh START that then refused with atomic_start_conflict; it now stays terminal. Released v2.2.x review stores were misclassified as malformed; they now classify as historical, and a selector-scoped exit handles them. On mounts that cannot represent private POSIX modes (WSL DrvFS without metadata, exFAT, SMB without POSIX extensions), the chmod 700 advice looped forever. Gentle AI now returns a typed refusal that names the workable continuations.
Included work: #4963 (issue #4433), #4899 (issue #2995), #5138 (issue #5112).
Engram on Antigravity
Antigravity now registers Engram as a plugin, and the Linuxbrew Engram path is recognized. Partial plugin writes are recovered from exact before-images. Settings and the complete plugin are installed before the old global registration is retired, so a failed migration cannot lose registration.
Included work: #5065 (issue #797), #5105, #5116, and #5118 (issue #1635), with stacked #5111 and #5113.
Pi, Homebrew, and state isolation
An absolute PI_CODING_AGENT_DIR is now honored only for the real user home. Before this change, tests and temporary homes could write into the developer's real Pi directory. The CodeGraph manifest is isolated for custom agent directories. Gentle AI's brew installs now run with HOMEBREW_NO_AUTO_UPDATE=1 and HOMEBREW_NO_INSTALL_CLEANUP=1 unless you set them yourself. On Windows, concurrent IncrementSyncs calls lost updates because of byte-range lock semantics. Same-process exclusion now uses a path-keyed mutex.
Included work: #5040 (issue #5039), #4985, #5012, #4914 (issue #4882).
Numbers
157 non-merge commits, 56 merged pull requests, and 8 unique GitHub PR authors since v3.7.0. By commit type the range is 86 fix, 26 docs, 21 test, 14 feat, 4 refactor, 3 chore, and 2 style, plus one README commit. Counts start at 204ccbd4, main's replay of v3.7.0, because a naive v3.7.0..v4.0.0 range lists 2,626 commits that already shipped; for the same reason GitHub's compare view below overstates this release. Against that baseline the release changes 1,576 files with 48,378 insertions and 123,473 deletions, most of them from the SDD retirement.
Install
brew install Gentleman-Programming/tap/gentle-aior
go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@v4.0.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: v3.7.0...v4.0.0