docs(plugin): retire version gates below the 0.80.0 floor - #706
Merged
Conversation
A version gate earns its place only while some live install predates it. kbagent self-updates on startup, so that population rounds to nothing -- only a standalone binary (self-update disabled), an explicit KBAGENT_AUTO_UPDATE=false, a dev tree, or a pip install stranded below 0.62.0 by the #424 rename can sit on an old version. Meanwhile the stale gate keeps making the agent refuse a command the user actually has, which CONTRIBUTING already calls strictly worse than no gate. Removes 223 tags across 18 agent-facing files (557 -> 334 gates). The tag goes, the content stays -- the guidance under these entries is still true, so not a word of it was deleted. Out of scope, deliberately: - changelog.py: the historical record; the version IS the content. - src/**/*.py except commands/context.py: developer comments are provenance and no agent reads them. - 'X+' inside a sentence: often load-bearing prose ('created by < 0.66.1 stay dormant until re-run on 0.66.1+'). - Safety gates at any age: sync pull --force (pre-0.53.0 it silently stranded local edits), the plaintext-secret audit (a false all-clear on a leaked credential), manage-token default-deny, the --deny-writes firewall, the dev-portal human-in-the-loop rule, and the sync trust cluster. Adds 'make gate-floor-report' (--list-below) so the next floor bump has a worklist instead of a hand-rolled grep, and documents the policy as release checklist step 4b.
padak
force-pushed
the
claude/retire-stale-version-gates
branch
from
August 26, 2026 17:32
6e530f4 to
85a5c4e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Retires the stale version gates you asked about, at the 0.80.0 floor, safety gates kept.
557 → 334 gates. 223 tags removed across 18 files. Not one word of content deleted.
Why
A gate earns its place only while some live install predates it. I checked
auto_update.pyrather than assuming:maybe_auto_update()self-upgrades pip/uv installs on startup, so the population an old gate protects rounds to nothing — only a standalone binary (self-update is disabled for brew/choco/apt/dnf), an explicitKBAGENT_AUTO_UPDATE=false, a dev tree, or a pip install stranded below 0.62.0 by the #424 rename can sit on an old version.Meanwhile the stale gate keeps doing damage, because
keboola-expert.mdRule 6 turns every tag into a refusal: the agent declines a command the user actually has. CONTRIBUTING already calls that strictly worse than no gate.The two failure modes are asymmetric, and that asymmetry is the whole argument:
No such command 'x', andkbagent context/--helpon the real install are authoritativeTag goes, content stays
This is de-tagging, not deletion. Nearly every old entry is still true — only the qualifier is obsolete:
The body ("omit
--config-idfor every config under a component…") is current, useful, and untouched.Safety gates kept, at any age
The rule applied: keep the tag wherever not knowing the version causes silent data loss or a false assurance rather than an error message. Six qualify, all verified by reading the section rather than the title:
sync pull --force(0.53.0)#-secret audit (0.55.0)--deny-writes/--deny-destructive(0.22.0)--theirs(0.72.0)Also out of scope, deliberately
changelog.py(33 gates) — the historical record; the version is the content.src/**/*.pyexceptcommands/context.py(13) —# DEPRECATED (since 0.43.4),UNAUTHORIZED = "…" # (0.40.0+). Developer provenance; no agent reads these files.X+inside a sentence (59) — frequently load-bearing prose.created by < 0.66.1 stay dormant until re-run on 0.66.1+is a migration instruction; stripping the version destroys it.With 0.25.0+:would becomeWith :.kbagent-pr-reviewer.md(3) — prose about the gate mechanism, using0.22.0+as an example.How, and what review caught
The de-tagger is conservative by construction: anything whose rewrite looks suspicious is skipped and reported rather than guessed at. The first attempt had two real bugs, both caught by reading the diff:
**Partial-state envelope**:into**Partial-state envelope*:. Fixed by not matching*around the parenthetical.. On projects with **branched storage**…— a line starting with a period. The rewritten script now detects and skips that shape; both instances were then fixed by hand (the bold sentence absorbs the full stop).New tooling
make gate-floor-report(--list-below VERSION) gives the next floor bump a worklist instead of a hand-rolled grep — the same class of hand-run command that lost the merge race in #702. Four tests.The policy is documented as release checklist step 4b, including the exclusions and the safety-gate rule, so this stays a decision rather than folklore.
Checks
make check: 6360 passed, 12 skipped.check_command_sync.pyOK (267 commands) — worth noting sincecommands-reference.mdtook 86 changed lines.keboola-expert.mdis well inside its 70 000 B budget.