From 2abaf08fcda3f099cced73c0351a55193d1afb37 Mon Sep 17 00:00:00 2001 From: Ryan Wolfe Date: Thu, 25 Jun 2026 15:40:50 -0400 Subject: [PATCH] feat: roll up to Agent CLI Guidelines v0.4.0 Add a machine-readable conformance block to `gfly schema --json` ({spec, version, level}) sourced from a new SPEC constant in the package __init__, and pin the conformance statement to exactly v0.4.0 Full (was an imprecise "v0.3") in the README and the for-agents reference. Backpressure (persistent cross-process throttle + circuit breaker, fail-fast) was already present; no change needed. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_012UFrhC6bXVpoiiL3yhj2HH --- CHANGELOG.md | 9 +++++++++ README.md | 2 +- docs/src/content/docs/reference/for-agents.md | 8 ++++---- src/gfly/__init__.py | 3 +++ src/gfly/cli.py | 3 ++- 5 files changed, 19 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fc8fd66..436b25d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added +- Machine-readable **conformance block** in `gfly schema --json`: + `{"spec": "agent-cli-guidelines", "version": "0.4.0", "level": "Full"}` (sourced from the + package `SPEC` constant), so an agent can verify the contract version from the binary. + +### Changed +- Pinned the conformance statement to **Agent CLI Guidelines v0.4.0, Full** (was an imprecise + "v0.3") across the README and the for-agents reference. + ## [0.2.0] - 2026-06-25 Reaches **Agent CLI Guidelines v0.3, Full**. diff --git a/README.md b/README.md index 4a8bd90..b8220ec 100644 --- a/README.md +++ b/README.md @@ -176,7 +176,7 @@ throttle/block), so an agent can back off, switch backend, or report instead of ## For agents -> Follows the [Agent CLI Guidelines](https://aclig.dev) (v0.3, **Full**) — read-only by default, +> Follows the [Agent CLI Guidelines](https://aclig.dev) (**v0.4.0, Full**) — read-only by default, > structured, self-describing, stable exit codes. ```bash diff --git a/docs/src/content/docs/reference/for-agents.md b/docs/src/content/docs/reference/for-agents.md index ca6a21e..492d244 100644 --- a/docs/src/content/docs/reference/for-agents.md +++ b/docs/src/content/docs/reference/for-agents.md @@ -256,11 +256,11 @@ gfly search JFK LHR \ ## Conformance -gfly follows the [Agent CLI Guidelines](https://aclig.dev) at **v0.3, Full** — every Core invariant +gfly follows the [Agent CLI Guidelines](https://aclig.dev) at **v0.4.0, Full** — every Core invariant (read-only by default, stdout/stderr discipline, stable `--json` schema, documented exit codes, -`--no-input` hard-fail, machine-readable `schema`, structured errors, bounded output, untrusted-text -fencing, append-only fields) plus the Full SHOULDs, including the ones the v0.2/v0.3 revisions added -for scraped-backend tools: +`--no-input` hard-fail, machine-readable `schema` with a `conformance` block, structured errors, +bounded output, untrusted-text fencing, append-only fields) plus the Full SHOULDs, including the ones +the v0.2/v0.3/v0.4 revisions added for scraped-backend tools: - **Backpressure** — a persistent, cross-process throttle with a circuit breaker; fail-fast by default (see [rate limits](/guides/rate-limits/)). diff --git a/src/gfly/__init__.py b/src/gfly/__init__.py index 31a064b..8028154 100644 --- a/src/gfly/__init__.py +++ b/src/gfly/__init__.py @@ -17,3 +17,6 @@ def _version() -> str: __version__ = _version() + +# Agent CLI Guidelines version this tool conforms to (declared in `schema`). +SPEC = "0.4.0" diff --git a/src/gfly/cli.py b/src/gfly/cli.py index c01db62..69416ac 100644 --- a/src/gfly/cli.py +++ b/src/gfly/cli.py @@ -23,7 +23,7 @@ import click -from . import __version__ +from . import SPEC, __version__ from . import auth as authmod from . import backend as be from . import throttle @@ -570,6 +570,7 @@ def schema(ctx, **_): "tool": "gfly", "version": __version__, "schemaVersion": SCHEMA_VERSION, + "conformance": {"spec": "agent-cli-guidelines", "version": SPEC, "level": "Full"}, "commands": info, "exit_codes": exit_table(), "safety": {"allow_mutations": rt.allow_mutations, "dry_run": rt.dry_run,