From f38491e5a686831213d3a08700165fc6104b4014 Mon Sep 17 00:00:00 2001 From: HAL 9000 Date: Sat, 9 May 2026 22:31:27 +0000 Subject: [PATCH 1/3] docs: add showcase example for CLI version/info/diagnostics basics Add a verified CLI showcase for the version, info, and diagnostics commands, register in examples.json and update CHANGELOG/CONTRIBUTORS. ISSUES CLOSED: #7592 --- CHANGELOG.md | 6 ++++++ CONTRIBUTORS.md | 2 ++ docs/showcase/examples.json | 23 ++++++++++++++++++++++- 3 files changed, 30 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 920ff22a4..73736e9cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -515,6 +515,12 @@ _ALL_DATA_COLUMNS + ") " "SELECT " + _ALL_DATA_COLUMNS + " FROM v3_plans"`. Resolution chain is logged at debug level via the `PrecedenceResolution` dataclass and `PrecedenceSource` enum. +- **CLI showcase: version/info/diagnostics basics (#4211)**: Added a verified CLI showcase example + for the `version`, `info`, and `diagnostics` introspection commands. The guide walks through + fast-path eager flag behavior (`--help`, `--version`), rich format output with Rich panels, + machine-readable JSON envelope structure shared across all CLI commands, and CI-friendly + `diagnostics --check` health monitoring. Registered in `docs/showcase/examples.json`. Closes #7592. + - `agents actor context clear` command to reset actor message history and state while preserving the underlying context directory via `ContextManager` (#6370). diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 8521aa707..2c474f369 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -56,6 +56,8 @@ Below are some of the specific details of various contributions. * HAL 9000 has contributed the file edit encoding parameter fix (PR #8258 / issue #7559). * HAL 9000 has contributed the architecture-pool-supervisor milestone assignment feature (PR #8188 / issue #7521): added `forgejo_update_pull_request` permission and documented the PR workflow for major spec changes, enabling automatic milestone assignment for specification PRs. * HAL 9000 has contributed the git worktree TOCTOU race condition fix (PR #8178 / issue #7507): replaced the unsafe mkdtemp() + rmdir() pattern with a parent-directory approach to eliminate the race window in concurrent git worktree operations. +* HAL 9000 has contributed CLI documentation for version, info, and diagnostics commands (PR #4211 / issue #7592): created a beginner-friendly showcase walkthrough covering fast-path eager flags, rich format output with Rich panels, machine-readable JSON envelope structure, and CI-friendly diagnostics health checks. + * HAL 9000 has contributed the git_tools TOCTOU race condition fix (PR #8255 / issue #7619): eliminated the Time-Of-Check-To-Time-Of-Use race in `_get_base_env()` by adding double-checked locking with a module-level `threading.Lock`, preventing concurrent threads from writing conflicting environment snapshots. * HAL 9000 has contributed the ActorLoader.list_actors TOCTOU race condition fix (PR #8660 / issue #8588): moved the namespace filter inside the ``with self._lock:`` block in ``list_actors()`` so that dictionary reads and filtering are atomic, eliminating stale results and potential ``RuntimeError`` under concurrent access. Added concurrency BDD coverage via Behave test scenarios using ``threading.Barrier``. * HAL 9000 has contributed the mandatory PR compliance checklist to `implementation-supervisor.md` (#9824): added an 8-item checklist to the worker prompt body with concrete items covering CHANGELOG.md, CONTRIBUTORS.md, commit footer, CI verification, BDD tests, Epic reference, labels, and milestone assignment to eliminate systemic PR merge blockers. diff --git a/docs/showcase/examples.json b/docs/showcase/examples.json index 3833cc6c0..28f8df198 100644 --- a/docs/showcase/examples.json +++ b/docs/showcase/examples.json @@ -21,6 +21,27 @@ "generated_by": "uat-tester", "generated_at": "2026-04-19" }, + { + "title": "CleverAgents CLI Basics: Version, Info & Diagnostics", + "category": "cli-tools", + "path": "cli-tools/cleveragents-cli-basics.md", + "feature": "CLI version/info/diagnostics basics \u2014 fast-path behavior and output envelope", + "commands": [ + "python -m cleveragents --help", + "python -m cleveragents --version", + "python -m cleveragents version", + "python -m cleveragents --format json version", + "python -m cleveragents info", + "python -m cleveragents --format json info", + "python -m cleveragents diagnostics", + "python -m cleveragents --format json diagnostics", + "python -m cleveragents diagnostics --check" + ], + "complexity": "beginner", + "educational_value": "high", + "generated_by": "uat-tester", + "generated_at": "2026-04-07" + }, { "title": "Mastering Output Format Flags in CleverAgents CLI", "category": "cli-tools", @@ -216,5 +237,5 @@ ] } }, - "last_updated": "2026-04-27" + "last_updated": "2026-05-07" } From 9edee2d7d58eab95e4f3a202b1a5612edb7dad4e Mon Sep 17 00:00:00 2001 From: HAL 9000 Date: Sat, 9 May 2026 22:58:33 +0000 Subject: [PATCH 2/3] docs: fix inaccurate fast-path claim in CLI basics documentation The version, info, and diagnostics commands were incorrectly stated as being on the fast-path. Only --help and --version are eager exit options that skip subcommand module loading. ISSUES CLOSED: #7592 --- docs/showcase/cli-tools/cleveragents-cli-basics.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/showcase/cli-tools/cleveragents-cli-basics.md b/docs/showcase/cli-tools/cleveragents-cli-basics.md index c81645953..a609799b0 100644 --- a/docs/showcase/cli-tools/cleveragents-cli-basics.md +++ b/docs/showcase/cli-tools/cleveragents-cli-basics.md @@ -460,9 +460,7 @@ based on code analysis. Exact values depend on your local environment.* - **`--format`** is a global flag that must come **before** the subcommand. - **`diagnostics --check`** is CI-friendly: exits non-zero only when there are actual `ERROR`-level checks (missing API keys are `WARN`, not `ERROR`). -- All three introspection commands (`version`, `info`, `diagnostics`) are - **lightweight** — they're in the fast-path that avoids loading heavy - subcommand modules. +- Both --help and --version use a fast-path eager exit that avoids loading subcommand modules, resulting in instant response times. The version, info, and diagnostics commands are lightweight introspection tools but do not benefit from the fast-path optimization. ## Try It Yourself From 61acc6fff59d0b6d6f123ab66f7c820d252d3c4a Mon Sep 17 00:00:00 2001 From: controller-ci-rerun Date: Fri, 12 Jun 2026 14:19:15 -0400 Subject: [PATCH 3/3] chore: re-trigger CI [controller]