v2.6.0 — The Runtime Asks First

v2.6.0 — The Runtime Asks First

v2.6.0 is main at c24a724a, 34 non-merge commits after v2.5.0. No release candidate series this time: every change landed on main behind the ordinary PR gates, and this stable is the state of main once the Windows lane was green on it again.

Provenance: this release contains the c24a724a bytes. ci.yml and the Windows Full Suite are both green on that exact commit. checksums.txt covers all six archives, including gentle-ai-review-provider-contract-1.2.0.tar.gz and gentle-ai-release-provenance-v1.tar.gz, and its Minisign signature carries the trusted comment repo=Gentleman-Programming/gentle-ai;tag=v2.6.0. The post-publication verify job expects the provenance archive now (#4017), so this run verifies end to end.

What's new

Claude Code is reminded to preflight, by the runtime

v2.5.0 made the review entry rule explicit in the orchestrator contract (#4052): enter the lifecycle once per candidate, after the implementation is normalized and before reporting done, whenever the switch is on. Whether that happened still depended on the model honoring the text. Pi already had a deterministic pull at loop end; Claude Code had hooks but nothing for a hook to call.

Now it has one. gentle-ai review stop-hook --agent claude-code (#4071) records the session's starting candidate on SessionStart and, on Stop, prints one gentle-ai.review-stop-hook/v1 block reminder naming the exact STATUS command and START transition, at most once per session candidate. It stays silent when review mode is off, the worktree is clean, the cwd is not a repository, or the reminder already fired. Install and sync write both hooks into ~/.claude/settings.json as managed entries, and uninstall removes them while preserving every hook it does not own (#4067).

Pi gets its review contract back

Since gentle-pi took ownership of Pi's system prompt, gentle-ai had no channel for the review execution contract to reach a Pi session. The provider contract bundle now ships orchestration/pi.md (#4059), bumping CONTRACT_SEMVER from 1.1.0 to 1.2.0 additively, and Pi's STATUS, capture, group capture, and acknowledgement route through the registered facade tools rather than any raw CLI path (#4099). The other runtimes keep the native CLI contract unchanged.

The stale managed blocks an older build left in ~/.pi/agent/APPEND_SYSTEM.md (sdd-orchestrator, strict-tdd-mode, persona, codegraph-guidance, agent-routing) are stripped on install, sync, and uninstall (#4060, #4065). The file is preserved, only the blocks gentle-ai wrote are removed.

The #4040 recovery route resolves

sdd-attempt finish told callers to run gentle-ai review status --next-transition to obtain the expected untracked-inventory digest, and status never emitted it on the reachable path. Four users hit that closed loop across macOS, Linux, and Windows. Status now publishes a top-level eligible_untracked_inventory digest on every envelope as status/v7, advertised through capabilities/v2.5 with v6 still advertised, and sdd-attempt finish/settle lets the ledger own the freshness refusal so the message that names the digest and the rerun command is the one you see (#4066, 149b1189, ab4b8bb0, 38103b5c). A driven bench journey proves the route as a recovery, not just as a field (e54fade8, 67193488).

Archived SDD changes say so

gentle-ai sdd status returns a positive archived: { path } field and an archived recommended-action token once every phase is done and nothing is blocked, on both the OpenSpec and Engram backends (#4009). Before, an archived change was indistinguishable from one that never existed.

OpenCode structured untracked selection

An OpenCode agent hands back which untracked files belong in the candidate as a JSON selection; gentle-ai decodes it strictly, substitutes the provider-owned token, and executes the printed START transition verbatim (capabilities/v2.4, status/v6, #3998). Resuming an approved lineage's pending acknowledgement preserves the frozen selection instead of dropping it (#4108).

Breaking changes

• Provider contract bundle 1.2.0. Consumers that mirror the bundle must carry 1.2.0 to inject orchestration/pi.md. gentle-pi 2.3.0 pins v2.5.0 and bundle 1.1.0; the gentle-pi release that follows this one carries the v2.6.0 pin and the 1.2.0 bundle. Every previously published contract artifact stays byte-frozen under its digest pin, and capabilities/v2.3, v2.4, start/v4, status/v6, and consent/v3 are unchanged.
• Backup rollback no longer deletes untyped entries. A legacy manifest entry with an empty kind and Existed == false is preserved on rollback instead of deleted. Only entries the snapshot typed as regular files that the install proved it created are removed (#2021, 1931449c).
• Sync touches only the agents you selected. sync and CodeGraph guidance now derive their agent set from installed_agents in state.json instead of filesystem discovery (#3493). If you relied on sync writing into an agent you never selected but had installed, it stops.

Upgrade now

brew upgrade gentle-ai

Run gentle-ai sync after upgrading. Replacing the binary does not wire the new Claude Code Stop and SessionStart hooks into an existing setup, and it does not strip the stale managed blocks from an existing Pi system prompt file. Everything else takes effect on the next run.

What was fixed

Review lifecycle

• A malformed targeted validator or refuter result gets one corrective re-invocation with admission feedback before refusal, the refused payloads are preserved, and the terminal classification is provider_capture_result_refused with next_action: review.status instead of a generic code naming an action the operator cannot take (#4076).
• The targeted validator's passed polarity is explicit and contract-tested, and additive top-level provider metadata is admitted without weakening required, nested, semantic, or authority validation (#4058).
• The orchestrator contract names when the lifecycle is entered, so an enabled switch is preflighted before completion in every runtime (#4052).
• Claude Agent delegations resolve a model for organic work, not only inside the lazy SDD workflow (#4062).

Install, sync, update

• OpenCode "Configure Models" reads the effective config, including opencode.jsonc custom providers with comments and trailing commas, merges them with runtime-discovered models, and install and sync no longer overwrite an existing or intentionally cleared model selection (#3988).
• The update cooldown timestamp is written under the canonical install-state lock through a fresh read and reconciled write, so a background cooldown update can no longer revert a concurrent review mode disable (#4083).

Backup and restore

• Snapshots preserve directories and symlinked directories instead of collapsing them to regular files, carrying a PathKind and LinkTarget through manifest, snapshot, and restore (#2021).
• Restore fails closed on an ancestor symlink escaping the backup root and on a symlink whose on-disk type or target diverges from the manifest, validates a link target only when it has to recreate the link, and creates the parent directory first (35de4015, 2bb040d3, 5e6f90ed).

Release

• Post-publication verification and the promotion preflight expect the provenance archive, which is why v2.5.0's verify job reported failure on a sound release (#4017).

Windows

The lane went red again after #4083 because its two cooldown concurrency tests built the candidate binary as gentle-ai without .exe, which Windows refuses to execute (#4168, #4169). Test-only, and green on this commit. #4014 had already closed the three held-LOCK and short-path test defects from the previous red streak.

Docs

The README was restructured for progressive onboarding and every guide updated to stable v2.5.0 facts (#3890), with the star history chart, site, and wiki links in the header (#4069, #4073) and an about-the-author section.

Numbers

34 non-merge commits since v2.5.0 from nine contributors. At publication, 694 issues are open.

Install

brew install Gentleman-Programming/tap/gentle-ai

or

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

Signed platform archives below: linux_amd64, linux_arm64, darwin_amd64, darwin_arm64, plus gentle-ai-review-provider-contract-1.2.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.5.0...v2.6.0