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

cli_router-0.3.2/.github/actionlint.yaml

@@ -0,0 +1,3 @@
+self-hosted-runner:
+  labels:
+    - mothership

cli_router-0.3.2/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python-development:
+        dependency-type: development
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

cli_router-0.3.2/.github/workflows/agent-drift-watchdog.yml

@@ -0,0 +1,255 @@
+name: Agent drift watchdog
+
+# Scheduled loop: inspect live model catalogs on the self-hosted runner. A
+# single-runner removal opens an advisory issue; only a maintainer-confirmed
+# manual run may invoke the local patch agent and open a review-required PR.
+#
+# SECURITY: this runs on a self-hosted runner that holds your subscription
+# credentials. It is triggered ONLY by the schedule or a maintainer clicking
+# "Run workflow" — never by pull_request, and never by fork code. Do not add
+# untrusted triggers to this file.
+
+on:
+  schedule:
+    - cron: "0 14 * * 1" # Mondays 14:00 UTC
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Detect and report drift only; do not patch or open a PR"
+        type: boolean
+        default: true
+      confirm_removals:
+        description: "Confirm this runner's missing models should be patched"
+        type: boolean
+        default: false
+
+permissions: {}
+
+concurrency:
+  group: agent-drift-watchdog
+  cancel-in-progress: false
+
+jobs:
+  preflight:
+    runs-on: [self-hosted, mothership]
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      issues: write
+    outputs:
+      proceed: ${{ steps.gate.outputs.proceed }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - id: gate
+        name: Circuit breaker + kill switch
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          DAILY_CAP: ${{ vars.AGENT_DAILY_CAP || '10' }}
+        run: python3 scripts/agent/preflight.py
+
+  drift:
+    needs: preflight
+    if: needs.preflight.outputs.proceed == 'true'
+    runs-on: [self-hosted, mothership]
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      issues: write
+    outputs:
+      patch_ready: ${{ steps.package.outputs.patch_ready }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Install cli-router in an isolated environment
+        run: |
+          python3 -m venv "$RUNNER_TEMP/cli-router-venv"
+          "$RUNNER_TEMP/cli-router-venv/bin/python" -m pip install -e .
+          echo "$RUNNER_TEMP/cli-router-venv/bin" >> "$GITHUB_PATH"
+
+      - name: Detect drift
+        id: detect
+        env:
+          CONFIRM_REMOVALS: ${{ inputs.confirm_removals || 'false' }}
+        run: |
+          confirm_arg=""
+          if [ "$CONFIRM_REMOVALS" = "true" ]; then
+            confirm_arg="--confirm-removals"
+          fi
+          python3 scripts/agent/detect_drift.py --timeout 15 $confirm_arg | tee drift.json
+          drift=$(python3 -c "import json; print(str(json.load(open('drift.json'))['drift']).lower())")
+          candidate=$(python3 -c "import json; print(str(json.load(open('drift.json'))['candidate_drift']).lower())")
+          echo "drift=$drift" >> "$GITHUB_OUTPUT"
+          echo "candidate=$candidate" >> "$GITHUB_OUTPUT"
+
+      - name: No candidate drift
+        if: steps.detect.outputs.candidate != 'true'
+        run: echo "No retired shipped models. Nothing to do."
+
+      - name: Report candidate drift for maintainer confirmation
+        if: steps.detect.outputs.candidate == 'true' && steps.detect.outputs.drift != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh label create agent-drift --color 1d76db --description "Model-list drift candidate" --force
+          existing=$(gh issue list --label agent-drift --state open --json number --jq '.[0].number')
+          body="$(cat drift.json)"
+          if [ -n "$existing" ]; then
+            gh issue comment "$existing" --body "Fresh single-runner observation; confirmation is still required:
+
+          \`\`\`json
+          $body
+          \`\`\`"
+          else
+            gh issue create --label agent-created --label agent-drift \
+              --title "Provider model-list drift requires confirmation" \
+              --body "One runner observed a shipped fallback model missing. This can vary by account or CLI version, so no patch was applied.
+
+          Re-run this workflow manually with \`confirm_removals=true\` after verification.
+
+          \`\`\`json
+          $body
+          \`\`\`"
+          fi
+
+      - name: Dry run — report only
+        if: steps.detect.outputs.candidate == 'true' && inputs.dry_run == true
+        run: |
+          echo "Drift found; dry_run=true, not patching:"
+          cat drift.json
+
+      # --- The following steps run only when there is real drift and it's not a dry run ---
+
+      - name: Build agent prompt
+        if: steps.detect.outputs.drift == 'true' && inputs.dry_run != true
+        run: python3 scripts/agent/build_prompt.py drift.json | tee patch_prompt.txt
+
+      - name: Create isolated patch branch
+        if: steps.detect.outputs.drift == 'true' && inputs.dry_run != true
+        run: |
+          git switch -c "agent/drift-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          git config --local credential.helper ""
+
+      - name: Reject persistent runner GitHub authentication
+        if: steps.detect.outputs.drift == 'true' && inputs.dry_run != true
+        run: |
+          if env -u GH_TOKEN -u GITHUB_TOKEN -u GH_CONFIG_DIR gh auth status >/dev/null 2>&1; then
+            echo "Persistent gh authentication is available to the runner user; refusing to launch the patch agent." >&2
+            exit 1
+          fi
+
+      - name: Apply fix with local agent
+        if: steps.detect.outputs.drift == 'true' && inputs.dry_run != true
+        env:
+          GH_CONFIG_DIR: ${{ runner.temp }}/cli-router-empty-gh
+        run: |
+          mkdir -p "$GH_CONFIG_DIR"
+          env -u GH_TOKEN -u GITHUB_TOKEN -u ACTIONS_RUNTIME_TOKEN \
+            -u ACTIONS_ID_TOKEN_REQUEST_TOKEN -u ACTIONS_ID_TOKEN_REQUEST_URL \
+            bash scripts/agent/apply_drift_fix.sh patch_prompt.txt
+
+      - name: Validate agent patch scope
+        if: steps.detect.outputs.drift == 'true' && inputs.dry_run != true
+        run: python3 scripts/agent/validate_patch.py
+
+      - id: package
+        name: Package the validated patch
+        if: steps.detect.outputs.drift == 'true' && inputs.dry_run != true
+        run: |
+          set -euo pipefail
+          git diff --binary HEAD -- CHANGELOG.md cli_router/models.py tests/test_models.py > "$RUNNER_TEMP/drift.patch"
+          test -s "$RUNNER_TEMP/drift.patch"
+          echo "patch_ready=true" >> "$GITHUB_OUTPUT"
+
+      - name: Upload the validated patch
+        if: steps.package.outputs.patch_ready == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: validated-drift-patch
+          path: ${{ runner.temp }}/drift.patch
+          if-no-files-found: error
+          retention-days: 1
+
+  verify_patch:
+    needs: drift
+    if: needs.drift.outputs.patch_ready == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.12"
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: validated-drift-patch
+          path: ${{ runner.temp }}
+
+      - name: Apply and validate the isolated patch
+        run: |
+          git apply "$RUNNER_TEMP/drift.patch"
+          python3 scripts/agent/validate_patch.py
+
+      - name: Verify in an ephemeral read-only job
+        run: |
+          python -m pip install -e .
+          python -m pytest -q
+
+  publish:
+    needs: [drift, verify_patch]
+    if: needs.drift.outputs.patch_ready == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: validated-drift-patch
+          path: ${{ runner.temp }}
+
+      - name: Apply the verified patch
+        run: |
+          git apply "$RUNNER_TEMP/drift.patch"
+          python3 scripts/agent/validate_patch.py
+
+      - name: Open review-required PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          gh auth setup-git
+          git config user.name "cli-router-agent[bot]"
+          git config user.email "cli-router-agent@users.noreply.github.com"
+          branch="agent/drift-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          git switch -c "$branch"
+          git add -- cli_router/models.py tests/test_models.py CHANGELOG.md
+          git -c core.hooksPath=/dev/null commit -m "Fix provider model-list drift (automated)"
+          git push -u origin "$branch"
+
+          # Ensure labels exist (ignore errors if already created).
+          gh label create agent-created --color 5319e7 --description "Opened by an agent loop" 2>/dev/null || true
+          gh label create agent-drift   --color 1d76db --description "Model-list drift fix"     2>/dev/null || true
+
+          url=$(gh pr create \
+            --title "Fix provider model-list drift" \
+            --body "Automated by the drift watchdog. \`cli-router doctor\` found a retired shipped model; this updates \`DEFAULT_MODELS\`, the test, and the changelog. The full test suite passed on the runner.
+          The self-hosted runner supplied only a validated three-file patch; publication ran in this isolated GitHub-hosted job." \
+            --label agent-created --label agent-drift)
+          echo "Opened $url"

{cli_router-0.3.0 → cli_router-0.3.2}/.github/workflows/publish.yml

@@ -3,7 +3,6 @@ name: Publish to PyPI
 on:
   release:
     types: [published]
-  workflow_dispatch:
 
 permissions:
   contents: read
@@ -14,10 +13,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install test dependencies
@@ -26,14 +25,16 @@ jobs:
         run: python -m pip install -e .
       - name: Run tests
         run: python -m pytest tests -q
+      - name: Validate release identity
+        run: python scripts/check_release.py
 
   build:
     name: Build distributions
     runs-on: ubuntu-latest
     needs: test
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.12"
       - name: Install build tools
@@ -43,7 +44,7 @@ jobs:
       - name: Check distributions
         run: python -m twine check dist/*
       - name: Upload distributions
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: dist
           path: dist/
@@ -60,9 +61,9 @@ jobs:
 
     steps:
       - name: Download distributions
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: dist
           path: dist/
       - name: Publish package
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1

cli_router-0.3.2/.github/workflows/test.yml

@@ -0,0 +1,58 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install test dependencies
+        run: python -m pip install --upgrade pip pytest
+      - name: Install package
+        run: python -m pip install -e .
+      - name: Test
+        run: python -m pytest tests -q
+
+  quality:
+    name: Quality and package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.12"
+      - name: Install package and development tools
+        run: python -m pip install --upgrade pip -e ".[dev]"
+      - name: Lint
+        run: ruff check cli_router scripts tests
+      - name: Type check
+        run: mypy cli_router scripts
+      - name: Lint GitHub Actions workflows
+        run: |
+          curl --fail --silent --show-error --location \
+            --output /tmp/actionlint.tar.gz \
+            https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz
+          echo "8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8  /tmp/actionlint.tar.gz" \
+            | sha256sum --check --strict
+          tar -xzf /tmp/actionlint.tar.gz -C /tmp actionlint
+          /tmp/actionlint -color
+      - name: Test with coverage
+        run: coverage run -m pytest tests -q && coverage report
+      - name: Build package
+        run: python -m build
+      - name: Check distributions
+        run: python -m twine check dist/*

{cli_router-0.3.0 → 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.0 → cli_router-0.3.2}/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## 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.
+- Terminate the full subprocess process group on command timeout so provider helper processes do not survive an exit `124`.
+- Restored home-config-only TUI persistence; project-local and explicit configuration files are no longer silently rewritten.
+- Updated generated Hermes commands to the current non-interactive `hermes --oneshot` interface and corrected Grok `--single` argument ordering.
+- Hardened Doctor repair backends to run tool-free/read-only from an isolated temporary directory without GitHub repository tokens; providers without a safe tool-free mode are excluded.
+- Changed model drift removals to require explicit maintainer confirmation, isolated the patch agent from GitHub credentials, added a strict patch-file allowlist, and removed auto-merge from the watchdog.
+- Added release identity validation, Python 3.14 CI, Ruff, mypy, actionlint, branch-aware coverage, package checks, script tests, and Dependabot configuration.
+
 ## 0.3.0 - 2026-07-13
 
 - Added a `doctor` feature (`cli-router doctor`, `--repair`) to catch agent-CLI drift over time. `doctor` reports each provider's discovery health (CLI present? live model list parses?). With `--repair`, when a provider's CLI is installed and responding but its model list no longer parses, Doctor uses a working agent as an LLM parser — it runs the sick provider's own list command itself, hands only the raw text to the agent, and expects back a JSON array of model ids (LLM-as-parser, never LLM-as-operator). Recovered lists are written to `~/.cli-router/model-cache.yaml` (`cli_router.modelcache.ModelCache`), which layers between live discovery and the static `DEFAULT_MODELS` fallback, so the fix survives across runs without editing source. Model discovery and the TUI model pickers now consult that cache.

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.