cli-router 0.3.1__tar.gz → 0.3.2__tar.gz

{cli_router-0.3.1 → cli_router-0.3.2}/AGENTS.md

@@ -12,6 +12,23 @@ CLI-Router is a Python command-line orchestrator for external AI coding CLIs. It
 
 Keep that boundary intact. New behavior should make orchestration more reliable or configurable, not turn this package into an agent.
 
+## Agent Orientation and Continuity
+
+This repository keeps agent-neutral continuity files in the repository root. Every coding agent should use them, regardless of vendor or runtime:
+
+1. Read `AGENTS.md` for normative repository rules.
+2. Read `STATE.md` for the last verified project, release, CI, and operational state. Confirm time-sensitive claims against the repository or service before acting.
+3. Read `MEMORY.md` for durable lessons and known operational traps. Treat it as accumulated guidance, not a substitute for direct verification.
+4. Follow task-specific documentation under `docs/`, especially `docs/releasing.md` for releases.
+
+Keep the files distinct:
+
+- Update `AGENTS.md` when repository-wide working rules or invariants change.
+- Update `STATE.md` after releases or when the current branch, version, CI, publishing, or known-blocker state materially changes.
+- Update `MEMORY.md` when a reusable lesson is learned about this repository or its development environment.
+- Never record tokens, passwords, private keys, one-time device codes, credential contents, or other secrets in any repository file. Paths to credential stores and safe verification commands are acceptable.
+- If continuity documentation conflicts with executable evidence, prefer the evidence and correct the stale documentation in the same change when practical.
+
 ## Source Layout
 
 - `cli_router/cli.py`: argparse CLI entry point and command dispatch.
@@ -23,6 +40,7 @@ Keep that boundary intact. New behavior should make orchestration more reliable
 - `cli_router/failures.py`: external-tool failure classification and user-facing messages.
 - `cli_router/artifacts.py`: run directory and artifact persistence.
 - `cli_router/tools.py`: `tools list` and `tools test`.
+- `cli_router/receipts.py`: schema-versioned JSON receipts for automation-facing CLI output.
 - `cli_router/presets/`: packaged YAML defaults/presets.
 - `examples/`: user-facing example configs.
 - `tests/`: pytest coverage using fake subprocess CLIs, not real Claude/Codex calls.
@@ -84,13 +102,16 @@ Config lookup order is:
 4. `~/.config/cli-router/config.yaml`
 5. Built-in defaults from `cli_router/presets/generic.yaml`
 
-Config version is currently `version: 1`.
+Config version is currently `version: 2`; legacy `version: 1` remains supported. Version 2 requires `requires_cli_router`, which gives older routers a hard failure on the schema version rather than letting them ignore an unknown compatibility key.
 
 Supported placeholders are literal token replacements:
 
 - `{prompt}`
 - `{user_prompt}`
 - `{plan_path}`
+- `{previous_output}`
+- `{all_stage_outputs}`
+- `{target_root}`
 
 Do not switch to Python `str.format` semantics without a strong reason. Current literal replacement intentionally allows command snippets and prompts to contain unrelated braces.
 
@@ -98,7 +119,8 @@ Workflow stages use:
 
 - `id`: unique stage id within the workflow. The list order is the default execution order.
 - `tool`: primary tool name.
-- `fallback_tools`: optional ordered list of tool names to try after failed attempts.
+- `fallback_tools`: optional ordered list of tool names or `{tool, on}` policy mappings. Fallback is fail-closed: only `auth_required`, `usage_limit`, `timeout`, and `transport_failure` may be named, and legacy string entries use that same safe operational set.
+- `max_fallback_attempts`: optional nonnegative cap on fallback subprocesses actually started. Nonmatching policies are skipped without consuming the cap; a failed fallback's failure kind becomes the trigger for later policies. Fallback must never run after semantic/generic command failures, `unsupported_model`, `extraction_failed`, or configuration errors.
 - `enabled`: optional boolean; `false` skips the stage in default `run` and `implement`, while explicit `--stages` can still select it.
 - `input_template`: rendered prompt sent as `{prompt}` to the tool command.
 - `output_file`: planner output path, usually `PLAN.md`.
@@ -124,6 +146,16 @@ Tool config supports:
 - `output.extract`: top-level or dotted JSON field path.
 - `timeout_seconds`: optional positive number; timeout returns exit code `124`.
 - `provider`, `model`, and `effort`: optional TUI metadata for Model Config display/editing. These do not replace `command`.
+- `cwd`: optional working directory with literal placeholder replacement; workflows expose `{target_root}` as the router invocation directory.
+- `environment_mode`: `inherit` (default) or `allowlist`; allowlist mode starts with only names in `environment_allowlist`.
+- `environment`: string mapping applied after the inherited/allowlisted base; values support literal placeholders.
+- `environment_unset`: environment names removed after overrides.
+- `stdin`: `inherit` (default) or `closed`.
+- `redact_environment_values`: environment names whose nonempty values are replaced in captured/streamed output and recorded commands before artifact persistence. Without this explicit setting, preserve raw stdout/stderr.
+
+Top-level `requires_cli_router` accepts a PEP 440 specifier such as `">=0.3.2,<0.4.0"`. It is mandatory for config version 2. All config-loading commands must fail before execution when the running version is incompatible.
+
+Stable machine-readable output uses a single JSON object with `schema_version: 1`. `--json` is supported for `--version`, `check`, `plan`, `run`, `implement`, and `tools test`; preserve existing field names and semantics when extending the receipt schema.
 
 Diagnostic defaults support:
 
@@ -176,7 +208,7 @@ Fallback attempts include the tool name:
 - `planner.codex-planner.stderr`
 - `planner.codex-planner.extracted.md`
 
-Every run writes `run.yaml` containing stage summaries, commands, return codes, extracted output, `failure_kind`, workflow start/finish timestamps, total duration, and per-stage duration metrics.
+Every run writes `run.yaml` containing stage summaries, commands, return codes, extracted output, `failure_kind`, workflow start/finish timestamps, total duration, and per-stage duration metrics. Fallback attempt records also contain original-primary provenance (`primary_tool`, `primary_failure_kind`), immediate-trigger provenance (`trigger_tool`, `trigger_failure_kind`), `fallback_tool`, `fallback_reason`, and `fallback_attempt`.
 
 Persistent diagnostics write under `~/.cli-router/logs/` by default:
 
@@ -198,6 +230,8 @@ Current `failure_kind` values include:
 - `command_not_found`
 - `command_failed`
 - `extraction_failed`
+- `transport_failure`
+- `configuration_error`
 
 Known real-world messages are covered by tests, including:
 
@@ -262,7 +296,7 @@ These observations are environment-specific. Do not hardcode them into package d
 ## Design Constraints
 
 - Keep the CLI stable: `cli-router run`, `plan`, `implement`, `check`, `config show`, `tools list`, `tools test <name>`.
-- Keep dependencies minimal. Current runtime dependencies are `pyyaml` and `rich`; the CLI uses `argparse`. This is why the TUI remains Rich-based instead of adopting Textual without an explicit product decision.
+- Keep dependencies minimal. Current runtime dependencies are `packaging`, `pyyaml`, and `rich`; the CLI uses `argparse`. This is why the TUI remains Rich-based instead of adopting Textual without an explicit product decision.
 - Prefer list-form subprocess commands in examples and tests.
 - Preserve stdout/stderr exactly in artifacts. Do not redact or transform raw logs unless a user explicitly requests a privacy feature.
 - Avoid hidden behavior. If CLI-Router retries or falls back, make that visible through summaries and `run.yaml`.
@@ -285,3 +319,15 @@ Generated files that should normally remain untracked:
 - `.pytest_cache/`
 
 Before finalizing substantive changes, run `git status --short` and report any verification commands run.
+
+## Protected Branch and Release Workflow
+
+`main` is protected. Direct pushes are expected to fail with `GH006`; release metadata and all other changes must go through a pull request and the required checks. Do not bypass protection merely to complete a release.
+
+Use `docs/releasing.md` as the canonical release runbook. Important invariants:
+
+- Create the release commit on a branch, merge it through a green pull request, synchronize local `main`, and only then create the annotated release tag. The tag must point to the actual merged `main` commit, not a pre-merge or squash-source commit.
+- Pushing a tag does not publish the package. `.github/workflows/publish.yml` runs when a GitHub Release is published.
+- PyPI publishing uses GitHub Actions trusted publishing. Do not collect or add a local PyPI password/token for the normal release path.
+- Git transport and GitHub API authentication are separate. This repository's `origin` uses SSH, while `gh` stores its API credential persistently in the user's GitHub CLI configuration. A successful SSH test does not prove that `gh` is authenticated.
+- Before GitHub API work, run `gh auth status`. If the stored credential is invalid, reauthenticate once with `gh auth login`, verify the result, and reuse the persistent credential; do not start repeated login flows without checking status.

{cli_router-0.3.1 → cli_router-0.3.2}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.3.2 - 2026-07-19
+
+- Added fail-closed conditional fallback policies with per-tool `on` failure allowlists, `max_fallback_attempts`, transport-failure classification, and fallback provenance in run manifests. Legacy string fallbacks now use only the safe operational failure set and never retry semantic, extraction, unsupported-model, or configuration failures.
+- Fixed conditional fallback selection to scan past nonmatching policies, count only started fallback subprocesses against `max_fallback_attempts`, carry failed fallback classifications into later policy checks, and record both original-primary and immediate-trigger provenance.
+- Added schema-versioned JSON receipts for `--version`, `check`, `plan`, `run`, `implement`, and `tools test`, including config checksums, run/stage/model details, failure and fallback data, durations, outcomes, and artifact paths.
+- Captured config source and effective merged-config checksums immutably at load time so receipts remain bound to the configuration actually executed, and added provider reasoning effort to workflow and tool-test stage receipts.
+- Added tool-level cwd, environment allowlisting/overrides/unsets, closed stdin, and configured environment-value redaction for commands and captured/streamed output.
+- Added config schema v2 with mandatory `requires_cli_router` PEP 440 compatibility declarations, while retaining v1 support. Older routers reject the v2 schema instead of silently ignoring its safety requirement.
+
 ## 0.3.1 - 2026-07-19
 
 - Made workflow outcomes fail closed: `run` and `implement` now reject empty resolved stage lists, and `stop_on_failure: false` preserves the first failed stage as the overall result even when later stages succeed.

cli_router-0.3.2/MEMORY.md

@@ -0,0 +1,60 @@
+# Repository Memory
+
+This file preserves durable, high-signal lessons for maintainers and coding agents. It must never contain credential values, private keys, one-time device codes, or other secrets. Current facts belong in `STATE.md`; normative rules belong in `AGENTS.md`.
+
+## GitHub Authentication Is Split
+
+- Git transport and GitHub API authentication are independent. The repository remote uses SSH, so `ssh -T git@github.com` can succeed while `gh auth status` fails.
+- `gh` API authentication should persist across sessions in the user's GitHub CLI configuration. In this WSL environment the credential store is `/home/razor/.config/gh/hosts.yml`.
+- Never read, print, commit, or relay the token. Verify it safely with `gh auth status`; `gh auth token` may be used only with output suppressed when a script must test readability.
+- An SSH success message exits nonzero because GitHub does not provide shell access. Judge `ssh -T git@github.com` by its message, not only its exit code.
+- `gh auth setup-git` configures HTTPS Git credentials; it does not repair GitHub API authentication and is unnecessary for this repository's SSH remote.
+
+### 2026-07-19 Authentication Incident
+
+- The saved `gh` credential existed but GitHub rejected it as invalid. SSH push authentication remained healthy.
+- A single browser/device flow with `gh auth login --hostname github.com --git-protocol ssh --web` replaced the invalid API credential. After the user authorized it, `gh auth status` and suppressed token-readability checks succeeded without another login.
+- The correct response to a future failure is: check `gh auth status`, distinguish API auth from SSH auth and network failures, then reauthenticate only if GitHub reports the stored API credential invalid.
+- Device authorization codes are transient secrets. Show them only to the user during the active flow; never save them in repository documentation, logs, commits, or chat summaries intended for reuse.
+
+## Protected Main Changes the Release Order
+
+- Direct pushes to `main` fail with `GH006`; this is expected protection, not an authentication failure.
+- Start release metadata work on a release branch, push it, open a pull request, and wait for all required jobs.
+- The repository commonly squash-merges pull requests. A tag created on the source commit before the squash would not point to the final `main` commit.
+- Create the annotated version tag only after fetching the merged `main`. Verify the tag's peeled commit matches `origin/main` before pushing it.
+- If an unpushed local tag points to the source commit, it is safe to recreate it at the identical merged tree. If a tag has already been pushed or a release may have published, stop and assess before rewriting it; do not force-update a public release tag casually.
+
+## Publishing Mechanics
+
+- A tag push alone does not publish CLI-Router. Publishing starts when a non-draft GitHub Release is published for the tag.
+- `.github/workflows/publish.yml` performs tests, release-identity validation, build, Twine checks, artifact handoff, and PyPI trusted publishing.
+- Trusted publishing uses GitHub OIDC. A normal release should not need `TWINE_PASSWORD`, `PYPI_API_TOKEN`, or a manual upload from a maintainer machine.
+- Monitor the release workflow through the final `Publish CLI-Router to PyPI` job. A successful build job alone does not prove publication.
+- Independently verify publication from a fresh virtual environment using the public PyPI index and the exact version. Check both `importlib.metadata.version("cli-router")` and `cli_router.__version__`, then run `cli-router check`.
+
+## Local Verification Environment
+
+- System Python may be protected by PEP 668 or lack package metadata and development tools. An uninstalled checkout can make `tests/test_version.py` fail even when the source versions agree.
+- Use a temporary virtual environment, install `-e ".[dev]"`, and run tests, Ruff, mypy, coverage, CLI smoke checks, release identity, build, and Twine there.
+- Build release artifacts in a fresh temporary output directory to avoid confusing stale `dist/` files with the current release.
+- Network isolation can prevent build dependencies from resolving. Treat dependency-download failures separately from code failures and rerun with the environment's approved network mechanism.
+
+## PyYAML Treats `on` as a YAML 1.1 Boolean
+
+- PyYAML's safe loader parses an unquoted `on:` mapping key as boolean `true`, even though users naturally write conditional fallback policies with `on:`.
+- CLI-Router normalizes boolean `true` back to the documented `on` key inside fallback policy mappings before validation. Preserve this normalization unless the entire loader is deliberately migrated to YAML 1.2 semantics.
+
+## Compatibility Keys Need a Schema Bootstrap
+
+- A router released before `requires_cli_router` existed can ignore that unknown top-level key, so the key alone cannot protect a safety-sensitive config from old binaries.
+- Config version 2 is the bootstrap boundary: old routers that only accept version 1 fail immediately, while new routers require and evaluate `requires_cli_router`. Keep legacy version 1 support, including treating configs with no explicit version as v1.
+
+## Fallback Policies Filter; Attempt Caps Count Processes
+
+- A nonmatching conditional fallback policy is skipped, not treated as a failed attempt and not charged against `max_fallback_attempts`.
+- After a fallback subprocess fails, its classified failure becomes the immediate trigger for later policies. Keep original-primary provenance separate from this immediate-trigger provenance so multi-hop chains remain auditable.
+
+## Config Receipt Identity Is a Load-Time Snapshot
+
+- Receipt identity must hash the exact source bytes read and the canonical effective merged config while loading. Never reread the source path when emitting a receipt: another process can replace the file between execution and receipt emission.

{cli_router-0.3.1 → cli_router-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-router
-Version: 0.3.1
+Version: 0.3.2
 Summary: A simple Python CLI router for AI planning and coding agents.
 Project-URL: Homepage, https://github.com/coolrazor007/cli-router
 Project-URL: Repository, https://github.com/coolrazor007/cli-router
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development
 Classifier: Topic :: Utilities
 Requires-Python: >=3.10
+Requires-Dist: packaging>=24.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Provides-Extra: dev
@@ -61,6 +62,8 @@ python -m pip install -e .
 
 ```bash
 cli-router --help
+cli-router --version
+cli-router --version --json
 cli-router
 cli-router tui
 cli-router plan "Add a health check endpoint"
@@ -69,9 +72,11 @@ cli-router run "Add a health check endpoint" --stages planner,review,coder
 cli-router implement
 cli-router implement --stages coder,review
 cli-router check
+cli-router check --json
 cli-router config show
 cli-router tools list
 cli-router tools test claude-planner
+cli-router tools test claude-planner --json
 cli-router runs
 cli-router runs show 2026-07-07T14-22-10
 ```
@@ -130,10 +135,18 @@ CLI-Router looks for config in this order:
 
 The TUI persists first-run setup and TUI edits to `~/.cli-router/config.yaml`. Project-local config files still take precedence when present.
 
+Project configs can require a compatible CLI-Router release with a PEP 440 version range. Every command, including `check`, fails before execution when the running package is outside the range. Use config `version: 2` with this declaration for a hard compatibility boundary: pre-feature routers reject the schema version instead of ignoring an unknown top-level key.
+
+```yaml
+version: 2
+requires_cli_router: ">=0.3.2,<0.4.0"
+```
+
 Minimal example:
 
 ```yaml
-version: 1
+version: 2
+requires_cli_router: ">=0.3.2,<0.4.0"
 
 defaults:
   plan_file: PLAN.md
@@ -159,6 +172,43 @@ tools:
       format: json
       extract: result
 
+  grok-reviewer:
+    type: grok
+    cwd: "{target_root}"
+    environment_mode: allowlist
+    environment_allowlist:
+      - HOME
+      - USER
+      - LOGNAME
+      - PATH
+      - GROK_HOME
+    environment:
+      TERM: dumb
+    environment_unset:
+      - GITHUB_TOKEN
+      - SSH_AUTH_SOCK
+    stdin: closed
+    redact_environment_values:
+      - GROK_TOKEN
+    command:
+      - grok
+      - --single
+      - "{prompt}"
+    output:
+      format: text
+
+  codex-planner:
+    type: codex
+    timeout_seconds: 120
+    command:
+      - codex
+      - --ask-for-approval
+      - never
+      - exec
+      - "{prompt}"
+    output:
+      format: text
+
   codex-coder:
     type: codex
     timeout_seconds: 120
@@ -221,7 +271,13 @@ workflows:
       - id: planner
         tool: claude-planner
         fallback_tools:
-          - codex-planner
+          - tool: codex-planner
+            on:
+              - auth_required
+              - usage_limit
+              - timeout
+              - transport_failure
+        max_fallback_attempts: 1
         input_template: |
           You are the planning model for a coding-agent handoff.
 
@@ -251,7 +307,7 @@ workflows:
           {user_prompt}
 ```
 
-Command args and templates support `{prompt}`, `{user_prompt}`, and `{plan_path}` placeholders.
+Command args, `cwd`, and configured environment values use literal placeholder replacement. Supported runtime placeholders include `{prompt}`, `{user_prompt}`, `{plan_path}`, `{previous_output}`, `{all_stage_outputs}`, and `{target_root}`. `{target_root}` is the directory from which CLI-Router was invoked.
 
 Workflow stages are modular:
 
@@ -272,7 +328,35 @@ Workflow stages are modular:
 - A stage with `output_file` writes its extracted output to that file.
 - A stage with `updates_plan: true` makes later `{plan_path}` placeholders point to its `output_file`.
 
-When a stage command fails, CLI-Router records stdout/stderr and classifies common failures. Usage-limit messages such as provider quota, rate-limit, or 429 errors are reported as usage-limit failures. Authentication failures such as provider login errors are reported as `auth_required` and include the provider's first error line. Commands can set `timeout_seconds`; timed-out commands are recorded with exit code `124`. A stage can define `fallback_tools` to try alternate configured tools in order after a failed primary tool.
+When a stage command fails, CLI-Router records stdout/stderr and classifies common failures. Usage-limit messages such as provider quota, rate-limit, or 429 errors are reported as usage-limit failures. Authentication failures such as provider login errors are reported as `auth_required` and include the provider's first error line. Network/connection errors are classified as `transport_failure`. Commands can set `timeout_seconds`; timed-out commands are recorded with exit code `124`.
+
+Fallback is fail-closed and only available for the operational failure kinds `auth_required`, `usage_limit`, `timeout`, and `transport_failure`. A structured fallback selects the allowed kinds with `on`; `max_fallback_attempts` caps how many alternates may run. Legacy string entries remain supported as shorthand for the full safe operational set. CLI-Router never falls back after generic command/semantic failures, unsupported-model configuration, malformed structured output (`extraction_failed`), or runtime configuration errors. Successful extracted verdicts such as `FAIL`, `PASS_WITH_WARNINGS`, or `INCONCLUSIVE` are final stage output and do not trigger fallback.
+
+Fallback policies are scanned in configured order. Policies that do not allow the current failure are skipped without consuming `max_fallback_attempts`; the cap counts only fallback subprocesses actually started. After a fallback fails, its failure kind becomes the trigger evaluated by later policies.
+
+Each fallback attempt records the original `primary_tool` and `primary_failure_kind`, the immediate `trigger_tool` and `trigger_failure_kind`, `fallback_tool`, `fallback_reason: allowed_failure_kind`, and the one-based `fallback_attempt` in `run.yaml`.
+
+Tool execution inherits the router process environment and stdin by default for backward compatibility. `environment_mode: allowlist` starts from only `environment_allowlist`; `environment` then adds or overrides values, and `environment_unset` removes named values. `stdin: closed` connects the child to the null device. `redact_environment_values` names environment variables whose nonempty values are replaced in captured stdout, stderr, streamed output, and the recorded command before artifacts are written. This is an explicit privacy mode: without it, raw output remains unchanged.
+
+## Machine-readable output
+
+`--json` is supported by `--version`, `check`, `plan`, `run`, `implement`, and `tools test` (place it after the subcommand for command-specific use). Each invocation prints exactly one JSON object with `schema_version: 1`. The stable envelope includes:
+
+- CLI-Router version and command.
+- Config source, the SHA-256 checksum of the exact source bytes loaded, and the SHA-256 checksum of the canonical effective merged config. These values are captured at load time and do not change if the source file is rewritten during execution.
+- Workflow, run ID/directory, duration, exit code, overall outcome, and error.
+- Whether fallback was used and why.
+- Per-attempt stage, tool, provider/model/reasoning effort, attempt number, exit code, failure kind, duration, fallback provenance, and artifact paths.
+
+Examples:
+
+```bash
+cli-router --version --json
+cli-router check --json
+cli-router tools test grok-reviewer --json
+cli-router run "Review this target" --json
+cli-router implement --json
+```
 
 ## Artifacts
 
@@ -322,3 +406,7 @@ python -m pip install --upgrade build twine
 python -m build
 python -m twine check dist/*
 ```
+
+The protected-branch, tagging, GitHub Release, trusted PyPI publishing, authentication, and public-package verification procedure is documented in the [release runbook](https://github.com/coolrazor007/cli-router/blob/main/docs/releasing.md).
+
+For cross-agent continuity, repository rules live in [AGENTS.md](https://github.com/coolrazor007/cli-router/blob/main/AGENTS.md), the last verified operational state lives in [STATE.md](https://github.com/coolrazor007/cli-router/blob/main/STATE.md), and durable environment lessons live in [MEMORY.md](https://github.com/coolrazor007/cli-router/blob/main/MEMORY.md). These files are intentionally tool- and vendor-neutral.

{cli_router-0.3.1 → cli_router-0.3.2}/README.md

@@ -26,6 +26,8 @@ python -m pip install -e .
 
 ```bash
 cli-router --help
+cli-router --version
+cli-router --version --json
 cli-router
 cli-router tui
 cli-router plan "Add a health check endpoint"
@@ -34,9 +36,11 @@ cli-router run "Add a health check endpoint" --stages planner,review,coder
 cli-router implement
 cli-router implement --stages coder,review
 cli-router check
+cli-router check --json
 cli-router config show
 cli-router tools list
 cli-router tools test claude-planner
+cli-router tools test claude-planner --json
 cli-router runs
 cli-router runs show 2026-07-07T14-22-10
 ```
@@ -95,10 +99,18 @@ CLI-Router looks for config in this order:
 
 The TUI persists first-run setup and TUI edits to `~/.cli-router/config.yaml`. Project-local config files still take precedence when present.
 
+Project configs can require a compatible CLI-Router release with a PEP 440 version range. Every command, including `check`, fails before execution when the running package is outside the range. Use config `version: 2` with this declaration for a hard compatibility boundary: pre-feature routers reject the schema version instead of ignoring an unknown top-level key.
+
+```yaml
+version: 2
+requires_cli_router: ">=0.3.2,<0.4.0"
+```
+
 Minimal example:
 
 ```yaml
-version: 1
+version: 2
+requires_cli_router: ">=0.3.2,<0.4.0"
 
 defaults:
   plan_file: PLAN.md
@@ -124,6 +136,43 @@ tools:
       format: json
       extract: result
 
+  grok-reviewer:
+    type: grok
+    cwd: "{target_root}"
+    environment_mode: allowlist
+    environment_allowlist:
+      - HOME
+      - USER
+      - LOGNAME
+      - PATH
+      - GROK_HOME
+    environment:
+      TERM: dumb
+    environment_unset:
+      - GITHUB_TOKEN
+      - SSH_AUTH_SOCK
+    stdin: closed
+    redact_environment_values:
+      - GROK_TOKEN
+    command:
+      - grok
+      - --single
+      - "{prompt}"
+    output:
+      format: text
+
+  codex-planner:
+    type: codex
+    timeout_seconds: 120
+    command:
+      - codex
+      - --ask-for-approval
+      - never
+      - exec
+      - "{prompt}"
+    output:
+      format: text
+
   codex-coder:
     type: codex
     timeout_seconds: 120
@@ -186,7 +235,13 @@ workflows:
       - id: planner
         tool: claude-planner
         fallback_tools:
-          - codex-planner
+          - tool: codex-planner
+            on:
+              - auth_required
+              - usage_limit
+              - timeout
+              - transport_failure
+        max_fallback_attempts: 1
         input_template: |
           You are the planning model for a coding-agent handoff.
 
@@ -216,7 +271,7 @@ workflows:
           {user_prompt}
 ```
 
-Command args and templates support `{prompt}`, `{user_prompt}`, and `{plan_path}` placeholders.
+Command args, `cwd`, and configured environment values use literal placeholder replacement. Supported runtime placeholders include `{prompt}`, `{user_prompt}`, `{plan_path}`, `{previous_output}`, `{all_stage_outputs}`, and `{target_root}`. `{target_root}` is the directory from which CLI-Router was invoked.
 
 Workflow stages are modular:
 
@@ -237,7 +292,35 @@ Workflow stages are modular:
 - A stage with `output_file` writes its extracted output to that file.
 - A stage with `updates_plan: true` makes later `{plan_path}` placeholders point to its `output_file`.
 
-When a stage command fails, CLI-Router records stdout/stderr and classifies common failures. Usage-limit messages such as provider quota, rate-limit, or 429 errors are reported as usage-limit failures. Authentication failures such as provider login errors are reported as `auth_required` and include the provider's first error line. Commands can set `timeout_seconds`; timed-out commands are recorded with exit code `124`. A stage can define `fallback_tools` to try alternate configured tools in order after a failed primary tool.
+When a stage command fails, CLI-Router records stdout/stderr and classifies common failures. Usage-limit messages such as provider quota, rate-limit, or 429 errors are reported as usage-limit failures. Authentication failures such as provider login errors are reported as `auth_required` and include the provider's first error line. Network/connection errors are classified as `transport_failure`. Commands can set `timeout_seconds`; timed-out commands are recorded with exit code `124`.
+
+Fallback is fail-closed and only available for the operational failure kinds `auth_required`, `usage_limit`, `timeout`, and `transport_failure`. A structured fallback selects the allowed kinds with `on`; `max_fallback_attempts` caps how many alternates may run. Legacy string entries remain supported as shorthand for the full safe operational set. CLI-Router never falls back after generic command/semantic failures, unsupported-model configuration, malformed structured output (`extraction_failed`), or runtime configuration errors. Successful extracted verdicts such as `FAIL`, `PASS_WITH_WARNINGS`, or `INCONCLUSIVE` are final stage output and do not trigger fallback.
+
+Fallback policies are scanned in configured order. Policies that do not allow the current failure are skipped without consuming `max_fallback_attempts`; the cap counts only fallback subprocesses actually started. After a fallback fails, its failure kind becomes the trigger evaluated by later policies.
+
+Each fallback attempt records the original `primary_tool` and `primary_failure_kind`, the immediate `trigger_tool` and `trigger_failure_kind`, `fallback_tool`, `fallback_reason: allowed_failure_kind`, and the one-based `fallback_attempt` in `run.yaml`.
+
+Tool execution inherits the router process environment and stdin by default for backward compatibility. `environment_mode: allowlist` starts from only `environment_allowlist`; `environment` then adds or overrides values, and `environment_unset` removes named values. `stdin: closed` connects the child to the null device. `redact_environment_values` names environment variables whose nonempty values are replaced in captured stdout, stderr, streamed output, and the recorded command before artifacts are written. This is an explicit privacy mode: without it, raw output remains unchanged.
+
+## Machine-readable output
+
+`--json` is supported by `--version`, `check`, `plan`, `run`, `implement`, and `tools test` (place it after the subcommand for command-specific use). Each invocation prints exactly one JSON object with `schema_version: 1`. The stable envelope includes:
+
+- CLI-Router version and command.
+- Config source, the SHA-256 checksum of the exact source bytes loaded, and the SHA-256 checksum of the canonical effective merged config. These values are captured at load time and do not change if the source file is rewritten during execution.
+- Workflow, run ID/directory, duration, exit code, overall outcome, and error.
+- Whether fallback was used and why.
+- Per-attempt stage, tool, provider/model/reasoning effort, attempt number, exit code, failure kind, duration, fallback provenance, and artifact paths.
+
+Examples:
+
+```bash
+cli-router --version --json
+cli-router check --json
+cli-router tools test grok-reviewer --json
+cli-router run "Review this target" --json
+cli-router implement --json
+```
 
 ## Artifacts
 
@@ -287,3 +370,7 @@ python -m pip install --upgrade build twine
 python -m build
 python -m twine check dist/*
 ```
+
+The protected-branch, tagging, GitHub Release, trusted PyPI publishing, authentication, and public-package verification procedure is documented in the [release runbook](https://github.com/coolrazor007/cli-router/blob/main/docs/releasing.md).
+
+For cross-agent continuity, repository rules live in [AGENTS.md](https://github.com/coolrazor007/cli-router/blob/main/AGENTS.md), the last verified operational state lives in [STATE.md](https://github.com/coolrazor007/cli-router/blob/main/STATE.md), and durable environment lessons live in [MEMORY.md](https://github.com/coolrazor007/cli-router/blob/main/MEMORY.md). These files are intentionally tool- and vendor-neutral.

cli_router-0.3.2/STATE.md

@@ -0,0 +1,55 @@
+# Repository State
+
+Last verified: 2026-07-19 (America/Los_Angeles)
+
+This file records the current known state for maintainers and coding agents. Verify remote and time-sensitive facts before relying on them, and update this file when the state materially changes.
+
+## Current Release
+
+- Current published package version: `0.3.1`. Draft PR #8 prepares package and runtime identity `0.3.2`; it is not yet merged, tagged, released, or published.
+- Annotated tag `v0.3.1` points to release commit `a37b4960dd7467f19bdb767502c13dcdc522326f`, which was the verified `main` and `origin/main` tip when 0.3.1 was published.
+- GitHub Release: <https://github.com/coolrazor007/cli-router/releases/tag/v0.3.1>
+- PyPI package: `cli-router==0.3.1`, independently installed from the public PyPI index and verified to report metadata and runtime version `0.3.1`.
+- The `Unreleased` changelog section is empty after the 0.3.1 release; draft PR #8 stages its accepted changes under a dated 0.3.2 release section.
+- Issue #1, the empty-stage false green, is closed as completed and represented in the 0.3.1 changelog.
+
+## Repository and CI
+
+- Default branch: `main`.
+- `main` is protected and rejects direct pushes. Changes must be merged by pull request.
+- Required pull-request jobs currently comprise Python 3.10, 3.11, 3.12, 3.13, and 3.14 tests plus `Quality and package`.
+- The quality job runs Ruff, mypy, actionlint, branch-aware coverage with an 80% floor, package build, and Twine checks.
+- The 0.3.1 release PR was #6 and all six required jobs passed before merge.
+
+## Publishing
+
+- `.github/workflows/publish.yml` is triggered by a published GitHub Release, not by a tag push alone.
+- The publish workflow reruns the Python 3.10-3.14 test matrix and release-identity validation, builds and checks the distributions, and publishes through PyPI trusted publishing using GitHub OIDC.
+- The successful 0.3.1 publish run is <https://github.com/coolrazor007/cli-router/actions/runs/29706059649>.
+- Normal releases do not require a local PyPI API token or a manual `twine upload`.
+
+## Local Environment
+
+- Repository remote: `git@github.com:coolrazor007/cli-router.git`.
+- Git pushes authenticate with the existing SSH key.
+- GitHub API operations authenticate separately through `gh`.
+- As of the last verification, `gh auth status` succeeds for `coolrazor007`, and `gh` can read its persistently stored credential from `/home/razor/.config/gh/hosts.yml`.
+- Do not copy credential contents or transient device codes into this file.
+
+## Verification Baseline
+
+The 0.3.1 release was verified with:
+
+- 185 tests passing locally.
+- Ruff passing.
+- mypy passing for 22 source files.
+- Branch-aware coverage meeting the configured 80% floor.
+- CLI help and `cli-router check` smoke tests passing.
+- Release identity validation passing for `v0.3.1`.
+- Wheel and source distribution build and Twine checks passing.
+- A built-wheel installation smoke test passing.
+- A separate clean installation of `cli-router==0.3.1` from public PyPI reporting metadata and runtime version `0.3.1`, with `cli-router check` returning `Configuration OK`.
+
+## Known Blockers
+
+- No known blocker remains for the 0.3.1 release.

{cli_router-0.3.1 → cli_router-0.3.2}/cli_router/__init__.py

@@ -1,3 +1,3 @@
 """CLI-Router package."""
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"