v2.5.0 — Review Closes Where Proof Ends

v2.5.0 is main at f5dd1a6c, not a promoted release candidate. The v2.5.0-rc.1 through v2.5.0-rc.3 series measured this work as it went; the stable is the state of main after that measurement, with 212 non-merge commits since v2.4.0.

Provenance: this release contains the f5dd1a6c bytes. ci.yml and the Windows Full Suite are both green on that exact commit. checksums.txt covers all six archives, including the new gentle-ai-release-provenance-v1.tar.gz, and its Minisign signature carries the trusted comment repo=Gentleman-Programming/gentle-ai;tag=v2.5.0. The workflow's post-publication verify job reported failure on this run: its expected-asset list predates the provenance archive (#3854) and refused the extra file before checking anything else. I verified the signature and every checksum out of band; the script fix is a follow-up.

What's new

Receipt-driven development is stable

RDD leaves the candidate series. The review lifecycle that the three v2.5.0 candidates were built to prove — freeze once, review the frozen bytes, correct at most once, close at the last causal event — is now the stable contract: gentle-ai.review-integration/v2 at capabilities v2.4, with start/v4, status/v6, consent/v3, and the provider contract bundle at 1.1.0. Every previously published contract artifact stays byte-frozen under its digest pin.

It stays opt-in. Nothing reviews until you say so:

gentle-ai review mode enable --scope global
gentle-ai review mode status

What a review is, now:

• One frozen candidate, one record. START freezes the candidate and one compact authority record per host cwd + lineage owns the whole lifecycle: binding, epoch and revision, admitted lens, refuter and validator results, replay identity, correction state, and terminal disposition. Nothing reads two representations of the same truth mid-series.
• START hands you the way back in. A reviewing START returns start/v4 with next_transition.execute(review.status) and the complete command. The orchestrator runs what the provider returned; it never reconstructs selectors from prose.
• Approval is terminal and acknowledged. The final approving capture commits one pending acknowledgement token and returns review.acknowledge-approved; only that exact invocation burns the lineage. There is no FINALIZE, no compact receipt, and no delivery gate after the evidence is complete. Delivery follows your repository's ordinary policy: hooks, tests, CI.
• Global controls in the TUI. Enable, disable, and inspect the global mode from gentle-ai itself, with copy that says what the gates are: informational.
• Works where Git is not yet. Global mode persists outside a repository, and an unversioned workspace gets a local Git bootstrap before its first review.
• Every runtime, the same contract. Claude Code, Codex, OpenCode, and Pi share the Go provider contract; OpenCode targets resolve across worktrees, and the concurrent reviewer group contract extends to every review runtime.

SDD Research

A first-class, proposal-gated lane for auditable external evidence. Select it right after sdd-explore; it accepts only the versioned gentle-ai.sdd-research-capability/v1 declaration with an exact grant for documentation or open-web, and persists a gentle-ai.sdd-research/v1 artifact under the change (openspec/changes/{change}/research.md or sdd/{change}/research) recording questions, grants, sources, claim-to-source mappings, contradictions, uncertainty, and freshness. Once selected, a proposal requires done evidence, valid references, a ready backend, and confirmed product decisions.

SDD status v2

SDD status is one clean contract. Runtime state carries planning, task, verification, selected-untracked, and attempt truth, and nothing else: no review bindings, no receipts. Attempt settlement is independent of review. The declared artifact store is authoritative and phase agents read injected locators instead of detecting it. Archive projects a positive terminal status.

Themes

The visual-theme component installs selectable Gentleman and Gentleman-Cute themes for Claude Code and OpenCode, with a hue-separated syntax palette, and the TUI gained a reduced-motion spinner fallback.

Breaking changes

• Review closes at its last causal event. Compact receipts, FINALIZE-after-evidence, and delivery gates are retired. review validate and the gate commands are compatibility surfaces that report unmanaged; no retired receipt is an approval. Historical artifacts load through compatibility reads and never regain authority.
• Consumers must speak the stable contract. Released gentle-pi builds up to 2.2.0 pin gentle-ai v2.4.0 and decode only start/v3; they refuse this provider's envelopes by design. gentle-pi 2.3.0 carries the v2.5.0 pin and the matching decoders.
• SDD status v1 is gone. Retired binding, receipt, parser, consumer, fixture, alias, and finish-remediation replay surfaces refuse instead of being reinterpreted.
• Claude Code SDD commands carry the gentle-sdd- prefix. Claude Code resolves a command and a skill with the same name in favour of the skill, and the delegate-only SDD skills are not user-invocable, so /sdd-init and six other phase commands were refused for the user and misrouted the sub-agent. They are now /gentle-sdd-init, /gentle-sdd-new, /gentle-sdd-continue, and so on. The other runtimes keep the bare /sdd-* names.

Upgrade now

brew upgrade gentle-ai

Run gentle-ai sync after upgrading. Replacing the binary does not refresh the managed runtime assets already installed for your agents, and this release retires files (the unprefixed Claude Code SDD commands) that only sync removes.

What was fixed

Review lifecycle

• The repository context is a 70-byte digest again. It was 1017 bytes of base64 JSON carrying the repository root, common directory, and git directory, and it appeared three times in one STATUS response.
• A correction survives an untracked artifact appearing while it is made, a committed correction with an admitted companion path is classified the way validation admits it, and rejected validator attempts close atomically.
• A reviewer citation that names a candidate file by basename is admitted; binary candidate bytes are no longer forced into reviewer patches; one corrected reviewer result is retried and refused payloads are preserved.
• The intended-untracked selection handoff executes the printed START transition verbatim, committed paths are dropped from an inherited untracked declaration, the frozen exclude declaration survives re-entry, and the claim text reaches the refuter.
• Mode state updates are serialized and review mode commands route through one shared API. A clone-local enable cannot turn review on by itself, and the rdd_disabled continuation names the global exit.
• Grouped OpenCode reviewer relays and the reviewer system context are isolated; the Pi host relay preserves its runtime binding.
• Refusals describe what happened: read-only failures keep their scrubbed cause, the two capture-result host-mediated refusals are distinct, the Pi relay handshake is named instead of the kill switch, and every stop names a runnable inventory, capture, or recover command. The refusal ratchet baseline went from 130 entries to 9.

SDD

• The runtime ledger tolerates additive fields from a newer binary when every known field is byte-identical to the canonical encoding, and refuses a newer schema version with a message naming the upgrade. Inventories get a 64 MiB bound and an overflow names its path count.
• Attempts account for the files they create, the automatic gate accepts paths a design plans to create, refunds are capped at the configured ceiling, zero attempt budgets are refused, and exhausted rescope does not inherit another allowance.
• Verify names stale and post-remediation blockers in blockedReasons, and verify-to-archive routing is guarded.
• The settle contract, verify-report fence, and state.yaml dependsOn are aligned with the CLI; every compact settle refusal and complete verdict names its runnable exit, including a vanished worktree, a non-Git target, and a rejected record.
• Nested workspace projects are discovered, archive destination collisions are rejected, cross-repository runtime targets are blocked, and a declared store that resolves nothing is a conflict, not a fresh start.
• The dispatcher guard is correct in every runtime orchestrator, both Engram MCP tool shapes are granted to SDD agents, and the CodeGraph grant is skipped for empty tools contracts.

Install, sync, doctor, upgrade

• Install requires only the SDD paths OpenCode actually writes, resolves OpenCode plugin paths through the adapter, keeps an install when the auto-added engram fails, and no longer routes an archived Engram change to archive.
• Doctor classifies dangling ancestor symlinks, warns on managed config symlink loops, reports unreadable managed paths, and no longer offers sync as a remedy for dangling symlinks.
• Windows beta self-updates work and bypass the proxy for the beta module; the TUI requires terminal streams; Pi package installation reports progress and bounds manifest parsing.
• Sync includes Codex hooks in backup targets. Release provenance is deterministic, and a local build reports that it has no provenance instead of pretending.
• OpenCode discovers models from the runtime catalog, tolerates a log preamble in verbose output, bounds validator permissions, and removes managed legacy tool grants.

Skills and automation

• Subagents no longer minify code to chase the 400-line budget. Orchestrator guidance requires explicit change intent before implementation.
• Issue-creation automation constrains labels, duplicate checks, target identity, multi-select answers, and private read-back; delegated triage actions are allowed; protected label workflows are guarded.
• The trademark policy is written down, and Homebrew guidance clarifies tap-trust options.

Windows

The full suite runs on the Windows lane and is green on this commit. The parity work (#3891) fixed the failures that unblocking the lane surfaced; #4014 fixes the three test defects that had turned it red again since 589c5458, all test-only: two reads of a held LOCK through a foreign handle, which Windows byte-range locks refuse, and one 8.3 short-path comparison.

Numbers

212 non-merge commits since v2.4.0: 105 measured by rc.1, 60 more by rc.2, 18 more by rc.3, and 29 after it. At publication, 622 issues are open against 702 at rc.2.

Install

brew install Gentleman-Programming/tap/gentle-ai

or

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

Signed platform archives below: linux_amd64, linux_arm64, darwin_amd64, darwin_arm64, plus gentle-ai-review-provider-contract-1.1.0.tar.gz and gentle-ai-release-provenance-v1.tar.gz. checksums.txt is signed with the release Minisign key (checksums.txt.minisig); see docs/release-signing.md for verification. Windows installs from source with go install.

Full changelog: v2.4.0...v2.5.0