agex-cli 0.26.0__tar.gz → 0.27.0__tar.gz

agex_cli-0.27.0/.devague/frames/every-devex-command-now-closes-with-a-deterministi.json

@@ -0,0 +1,208 @@
+{
+  "slug": "every-devex-command-now-closes-with-a-deterministi",
+  "title": "Every devex command now closes with a deterministic, per-backend Next step micro-prompt telling the running agent exactly how to continue \u2014 the pr namespace footer convention becomes a cross-command guarantee.",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-05-29T14:19:33Z",
+  "updated": "2026-05-29T15:05:05Z",
+  "claims": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "Every devex command now closes with a deterministic, per-backend Next step micro-prompt telling the running agent exactly how to continue \u2014 the pr namespace footer convention becomes a cross-command guarantee.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h4",
+          "text": "Every command path that reaches stdout terminates in exactly one Next step footer block \u2014 the guarantee is total, not best-effort \u2014 verified by a test that runs every non-silent command and asserts a trailing footer.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "Autonomous coding agents (claude-code, codex, copilot, acp backends) that invoke devex commands non-interactively and must pick their next move without an LLM in the loop.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h6",
+          "text": "Every footer hint is phrased as an actionable instruction to the running agent (an imperative naming a concrete next command/move), never human-facing prose \u2014 asserted by a test/lint on hint form.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c3",
+      "kind": "after_state",
+      "text": "Every non-silent devex command (explain, learn, overview, doctor, gamify, hook read, plus the existing pr namespace) ends its markdown with a Next step footer naming a concrete next move, so the agent never has to infer what to run next.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h3",
+          "text": "For each non-silent command there is a deterministic mapping from its observable end-state to exactly one rule_key, so the footer is reproducible across identical inputs.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c4",
+      "kind": "before_state",
+      "text": "Today only the pr namespace ends with a Next step footer. explain, learn, overview, doctor and hook read end at EOF; gamify install has a one-off ad-hoc Next line. After every other command the agent must guess the next move.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h7",
+          "text": "A snapshot test of current non-pr command output confirms none emits a Next step footer today, so the gap this feature closes is demonstrated, not assumed.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "devex exists to give autonomous agents deterministic guidance. A command that ends without a next-move prompt leaves a decision gap the agent fills by guessing \u2014 non-deterministic behaviour in a tool whose whole premise is determinism. A closing micro-prompt makes the command surface self-chaining.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h8",
+          "text": "The footer is fully determined by command inputs plus project state with zero LLM/network/random input \u2014 identical inputs always yield an identical footer, asserted by a reproducibility test.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "Out of scope: rewriting command body content; LLM-generated footers; adding a footer to deliberately-silent commands such as hook write which emits empty stdout; and auto-executing the suggested command \u2014 the footer is a prompt, not an action, so no new side effects are introduced.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h9",
+          "text": "After the change hook write still emits empty stdout and no command gains a new network/file-write/sleep side effect from the footer \u2014 verified by the existing side-effect/invariant tests staying green.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c7",
+      "kind": "success_signal",
+      "text": "A test asserts every non-silent command stdout ends with the footer block, and that each backend YAML defines a hint for every rule key its command can emit, so there is no missing-hint KeyError at runtime.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h10",
+          "text": "Both guard tests (every-command-ends-with-a-footer; every reachable rule_key has a hint) exist, run in CI, and fail loudly when a command or rule_key is added without a hint.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c8",
+      "kind": "requirement",
+      "text": "The footer-rendering machinery now under commands/pr (the _footer renderer, the rule_key plus context decision pattern, and footer.md.j2) is promoted to core so every command shares one implementation.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h1",
+          "text": "After the machinery moves to core, the pr namespace footers are byte-identical and every existing pr footer test passes unchanged (pure relocation, no behaviour change).",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c9",
+      "kind": "requirement",
+      "text": "Each non-pr command gains a small next-step decision function returning rule_key plus context, and a hints block in its per-command assets/backends/backend.yaml, mirroring how the pr namespace is structured.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h2",
+          "text": "One enumerating test walks every (command, backend, reachable rule_key) triple and fails if any hint string is missing, proving coverage rather than assuming it.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c10",
+      "kind": "requirement",
+      "text": "Backend-agnostic commands that do not take --agent today (explain, doctor) must still end with a coherent Next step footer.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h5",
+          "text": "With --agent provided, explain/doctor render that backend's hint; with it omitted they render a neutral hint from a shared default; both paths are test-covered so the optional flag never yields a missing or empty footer.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [
+        {
+          "id": "q1",
+          "text": "How do explain and doctor (no --agent flag today) emit a per-backend Next step footer? (a) add optional --agent, neutral footer when omitted; (b) stay agnostic, emit one neutral footer with no per-backend phrasing; (c) make --agent required on them too, breaking their agnostic contract.",
+          "resolved": false,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c11",
+      "kind": "decision",
+      "text": "Reuse the existing mechanism unchanged \u2014 rule_key plus context resolved against a per-backend hints YAML and rendered through footer.md.j2 as a Next step block under a horizontal rule \u2014 rather than inventing a new footer format.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c12",
+      "kind": "non_goal",
+      "text": "This is not a generalized workflow or command-graph engine; the footer suggests a single sensible next move, it does not model, validate or enforce a sequence of commands.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c13",
+      "kind": "decision",
+      "text": "explain and doctor gain an OPTIONAL --agent flag: when provided the footer uses that backend's hints YAML, when omitted a backend-neutral footer is emitted from a shared default. Existing flagless calls keep working unchanged (non-breaking). [resolves q1, user choice]",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    }
+  ],
+  "open_vagueness": []
+}

agex_cli-0.27.0/.devague/plans/every-devex-command-now-closes-with-a-deterministi.json

@@ -0,0 +1,307 @@
+{
+  "slug": "every-devex-command-now-closes-with-a-deterministi",
+  "title": "Every devex command now closes with a deterministic, per-backend Next step micro-prompt telling the running agent exactly how to continue \u2014 the pr namespace footer convention becomes a cross-command guarantee.",
+  "frame_slug": "every-devex-command-now-closes-with-a-deterministi",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-05-29T15:12:32Z",
+  "updated": "2026-05-29T15:18:39Z",
+  "targets": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "Every devex command now closes with a deterministic, per-backend Next step micro-prompt telling the running agent exactly how to continue \u2014 the pr namespace footer convention becomes a cross-command guarantee."
+    },
+    {
+      "id": "h4",
+      "kind": "honesty",
+      "text": "Every command path that reaches stdout terminates in exactly one Next step footer block \u2014 the guarantee is total, not best-effort \u2014 verified by a test that runs every non-silent command and asserts a trailing footer."
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "Autonomous coding agents (claude-code, codex, copilot, acp backends) that invoke devex commands non-interactively and must pick their next move without an LLM in the loop."
+    },
+    {
+      "id": "h6",
+      "kind": "honesty",
+      "text": "Every footer hint is phrased as an actionable instruction to the running agent (an imperative naming a concrete next command/move), never human-facing prose \u2014 asserted by a test/lint on hint form."
+    },
+    {
+      "id": "c3",
+      "kind": "after_state",
+      "text": "Every non-silent devex command (explain, learn, overview, doctor, gamify, hook read, plus the existing pr namespace) ends its markdown with a Next step footer naming a concrete next move, so the agent never has to infer what to run next."
+    },
+    {
+      "id": "h3",
+      "kind": "honesty",
+      "text": "For each non-silent command there is a deterministic mapping from its observable end-state to exactly one rule_key, so the footer is reproducible across identical inputs."
+    },
+    {
+      "id": "c4",
+      "kind": "before_state",
+      "text": "Today only the pr namespace ends with a Next step footer. explain, learn, overview, doctor and hook read end at EOF; gamify install has a one-off ad-hoc Next line. After every other command the agent must guess the next move."
+    },
+    {
+      "id": "h7",
+      "kind": "honesty",
+      "text": "A snapshot test of current non-pr command output confirms none emits a Next step footer today, so the gap this feature closes is demonstrated, not assumed."
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "devex exists to give autonomous agents deterministic guidance. A command that ends without a next-move prompt leaves a decision gap the agent fills by guessing \u2014 non-deterministic behaviour in a tool whose whole premise is determinism. A closing micro-prompt makes the command surface self-chaining."
+    },
+    {
+      "id": "h8",
+      "kind": "honesty",
+      "text": "The footer is fully determined by command inputs plus project state with zero LLM/network/random input \u2014 identical inputs always yield an identical footer, asserted by a reproducibility test."
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "Out of scope: rewriting command body content; LLM-generated footers; adding a footer to deliberately-silent commands such as hook write which emits empty stdout; and auto-executing the suggested command \u2014 the footer is a prompt, not an action, so no new side effects are introduced."
+    },
+    {
+      "id": "h9",
+      "kind": "honesty",
+      "text": "After the change hook write still emits empty stdout and no command gains a new network/file-write/sleep side effect from the footer \u2014 verified by the existing side-effect/invariant tests staying green."
+    },
+    {
+      "id": "c7",
+      "kind": "success_signal",
+      "text": "A test asserts every non-silent command stdout ends with the footer block, and that each backend YAML defines a hint for every rule key its command can emit, so there is no missing-hint KeyError at runtime."
+    },
+    {
+      "id": "h10",
+      "kind": "honesty",
+      "text": "Both guard tests (every-command-ends-with-a-footer; every reachable rule_key has a hint) exist, run in CI, and fail loudly when a command or rule_key is added without a hint."
+    },
+    {
+      "id": "c8",
+      "kind": "requirement",
+      "text": "The footer-rendering machinery now under commands/pr (the _footer renderer, the rule_key plus context decision pattern, and footer.md.j2) is promoted to core so every command shares one implementation."
+    },
+    {
+      "id": "h1",
+      "kind": "honesty",
+      "text": "After the machinery moves to core, the pr namespace footers are byte-identical and every existing pr footer test passes unchanged (pure relocation, no behaviour change)."
+    },
+    {
+      "id": "c9",
+      "kind": "requirement",
+      "text": "Each non-pr command gains a small next-step decision function returning rule_key plus context, and a hints block in its per-command assets/backends/backend.yaml, mirroring how the pr namespace is structured."
+    },
+    {
+      "id": "h2",
+      "kind": "honesty",
+      "text": "One enumerating test walks every (command, backend, reachable rule_key) triple and fails if any hint string is missing, proving coverage rather than assuming it."
+    },
+    {
+      "id": "c10",
+      "kind": "requirement",
+      "text": "Backend-agnostic commands that do not take --agent today (explain, doctor) must still end with a coherent Next step footer."
+    },
+    {
+      "id": "h5",
+      "kind": "honesty",
+      "text": "With --agent provided, explain/doctor render that backend's hint; with it omitted they render a neutral hint from a shared default; both paths are test-covered so the optional flag never yields a missing or empty footer."
+    }
+  ],
+  "tasks": [
+    {
+      "id": "t1",
+      "summary": "Promote the footer-rendering machinery from commands/pr into core (pure relocation, no behaviour change)",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "A new core module (core/footer.py) exposes render_footer plus hint-loading, and footer.md.j2 moves to a core assets location",
+        "All pr scripts import the footer renderer from core and pr footer output is byte-identical to before (snapshot diff empty)",
+        "The entire existing pr footer test suite passes unchanged"
+      ],
+      "deps": [],
+      "covers": [
+        "c8",
+        "h1"
+      ]
+    },
+    {
+      "id": "t2",
+      "summary": "Add neutral-default footer resolution to the core renderer for when no backend is supplied",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "When render_footer is called with no backend it resolves hints from a shared neutral source and returns a valid Next step block",
+        "Unit test: the neutral path yields a non-empty footer and the backend-specific path is unchanged"
+      ],
+      "deps": [
+        "t1"
+      ],
+      "covers": [
+        "c10",
+        "h5"
+      ]
+    },
+    {
+      "id": "t3",
+      "summary": "Add an optional --agent flag to explain and doctor and wire their Next step footers (backend hint when given, neutral when omitted)",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "devex explain TOPIC and devex doctor accept an optional --agent and existing flagless invocations keep working unchanged",
+        "With --agent the footer uses that backend per-command hints, without it the neutral footer is emitted, and both paths are covered by tests",
+        "Each of explain and doctor has a next-step decision function and a hints block (backend yamls plus neutral)"
+      ],
+      "deps": [
+        "t2"
+      ],
+      "covers": [
+        "c10",
+        "h5",
+        "c9"
+      ]
+    },
+    {
+      "id": "t4",
+      "summary": "Add a Next step footer to learn (menu and topic views) with a decision function and per-backend hints",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "learn menu and learn TOPIC both end with a Next step footer chosen by a decision function returning a rule_key plus context",
+        "commands/learn/assets/backends per-backend yaml defines a hint for every rule_key learn can emit, for all four backends",
+        "Unit tests cover the menu and topic footers for at least one backend"
+      ],
+      "deps": [
+        "t1"
+      ],
+      "covers": [
+        "c9",
+        "c3"
+      ]
+    },
+    {
+      "id": "t5",
+      "summary": "Add a Next step footer to overview with a decision function and per-backend hints",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "overview ends with a Next step footer chosen by a decision function returning a rule_key plus context",
+        "commands/overview/assets/backends per-backend yaml defines a hint for every rule_key overview can emit, for all four backends",
+        "A unit test asserts the overview footer for at least one backend"
+      ],
+      "deps": [
+        "t1"
+      ],
+      "covers": [
+        "c9",
+        "c3"
+      ]
+    },
+    {
+      "id": "t6",
+      "summary": "Replace gamify ad-hoc Next line with the structured Next step footer for install and uninstall",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "gamify install and uninstall end with the structured footer and the old ad-hoc Next line is removed",
+        "commands/gamify/assets/backends per-backend yaml defines a hint for every rule_key gamify can emit, for all four backends",
+        "Unit tests cover the install and uninstall footers for at least one backend"
+      ],
+      "deps": [
+        "t1"
+      ],
+      "covers": [
+        "c9",
+        "c3"
+      ]
+    },
+    {
+      "id": "t7",
+      "summary": "Add a Next step footer to hook read while keeping hook write silent",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "hook read ends with a Next step footer chosen by a decision function, and hook write still emits empty stdout with no footer",
+        "commands/hook/assets/backends per-backend yaml defines a hint for every rule_key hook read can emit, for all four backends",
+        "Unit tests assert the hook read footer and that hook write output stays empty"
+      ],
+      "deps": [
+        "t1"
+      ],
+      "covers": [
+        "c9",
+        "c3"
+      ]
+    },
+    {
+      "id": "t8",
+      "summary": "Add cross-command footer-guarantee tests: total coverage, determinism, no new side effects, and the pre-change gap",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "A parametrized test runs every non-silent command and asserts stdout ends with exactly one Next step footer block",
+        "A determinism test runs each command twice on identical project state and asserts byte-identical footers (no LLM, network, or randomness)",
+        "A test asserts hook write emits empty stdout and that no command performs network, file-write, or sleep to build its footer",
+        "A test demonstrates the pre-change gap: with the footer block absent each command body contains no Next step marker"
+      ],
+      "deps": [
+        "t3",
+        "t4",
+        "t5",
+        "t6",
+        "t7"
+      ],
+      "covers": [
+        "c1",
+        "c3",
+        "c4",
+        "c5",
+        "c6",
+        "h3",
+        "h4",
+        "h7",
+        "h8",
+        "h9"
+      ]
+    },
+    {
+      "id": "t9",
+      "summary": "Add hint-coverage and hint-form guard tests wired into the existing CI test job",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "An enumerating test walks every command-backend-rule_key triple and fails if any hint string is missing",
+        "A hint-form test asserts each hint is an imperative addressed to the agent that names a concrete devex command or move, not human prose",
+        "Both guard tests run under the existing pytest CI job and fail loudly when a command or rule_key is added without a hint"
+      ],
+      "deps": [
+        "t3",
+        "t4",
+        "t5",
+        "t6",
+        "t7"
+      ],
+      "covers": [
+        "c2",
+        "c7",
+        "h2",
+        "h6",
+        "h10"
+      ]
+    }
+  ],
+  "risks": [
+    {
+      "id": "r1",
+      "text": "Exact neutral-footer hint phrasing for explain and doctor is unspecified; builder picks concise agent-facing wording",
+      "kind": "unknown_nonblocking",
+      "task_id": "t3"
+    },
+    {
+      "id": "r2",
+      "text": "The hint-form check (imperative naming a command) is heuristic and may need tuning to avoid false positives",
+      "kind": "follow_up",
+      "task_id": "t9"
+    }
+  ]
+}

{agex_cli-0.26.0 → agex_cli-0.27.0}/.github/workflows/test.yml

@@ -23,6 +23,47 @@ jobs:
       - run: uv pip install -e ".[dev]"
       - run: uv run pytest
 
+  # --------------------------------------------------------------------------
+  # SonarCloud CI-based analysis + coverage. SonarCloud is no longer in
+  # Automatic Analysis mode (the two modes are mutually exclusive), so this job
+  # is the sole analysis path: it generates coverage.xml (with repo-relative
+  # paths via pyproject [tool.coverage.run] so Sonar can match files) and runs
+  # the scanner, which
+  # reads sonar-project.properties (projectKey / organization / reportPaths)
+  # and the SONAR_TOKEN repo secret. Runs on PRs (new-code decoration) and on
+  # pushes to main (baseline). fetch-depth: 0 gives Sonar the full history it
+  # needs for accurate new-code / blame attribution.
+  # --------------------------------------------------------------------------
+  sonarcloud:
+    name: SonarCloud
+    runs-on: ubuntu-latest
+    # Promote a *presence flag* (not the secret) to job env so the scan step
+    # can gate on it — `secrets.*` isn't allowed in `if:`. Lets forks /
+    # token-less runs skip the scan rather than hard-fail. (Pattern from the
+    # sibling agentfront repo, whose CI-based SonarCloud scan is green.)
+    env:
+      SONAR_TOKEN_PRESENT: ${{ secrets.SONAR_TOKEN != '' }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: "3.12"
+      - run: uv venv
+      - run: uv pip install -e ".[dev]"
+      - run: uv run pytest --cov=src/devex --cov-report=xml --cov-report=term
+      # Pinned to v6 to match the sibling agentfront repo's working scan.
+      # The v7+/v8 scanner engine 404s on `api.sonarcloud.io/analysis/analyses`
+      # against SonarQube Cloud; v6 posts to sonarcloud.io directly.
+      - name: SonarCloud Scan
+        if: env.SONAR_TOKEN_PRESENT == 'true'
+        uses: SonarSource/sonarqube-scan-action@fd88b7d7ccbaefd23d8f36f73b59db7a3d246602  # v6
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: https://sonarcloud.io
+
   # --------------------------------------------------------------------------
   # Enforces that every PR touching code (src/, tests/, pyproject.toml) also
   # bumps the version in pyproject.toml. Without this, a merge to main that

{agex_cli-0.26.0 → agex_cli-0.27.0}/.gitignore

@@ -213,3 +213,12 @@ __marimo__/
 
 # Worktrees
 .worktrees/
+
+# devague working state (not committed by default)
+.devague/questions/
+
+.devague/reviews/
+
+# devague session pointers (transient)
+.devague/current
+.devague/current_plan

{agex_cli-0.26.0 → agex_cli-0.27.0}/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-05-29
+
+### Added
+
+- Cross-command `Next step:` footers: every non-silent command (`explain`, `learn`, `overview`, `doctor`, `gamify`, `hook read`, plus the `pr` namespace) now ends with a deterministic, per-backend agent-facing micro-prompt telling the running agent how to continue.
+- Optional `--agent` on `explain` and `doctor`: backend-specific footer when supplied, neutral footer when omitted (non-breaking; flagless calls keep working).
+- `core/footer.py` — shared, command-agnostic footer renderer (`render_footer` + `render_neutral_footer`) plus a neutral hints source `core/assets/backends/neutral.yaml`.
+- Per-command next-step decision functions and `hints:` blocks under `commands/<cmd>/assets/backends/<backend>.yaml`.
+- Footer-guarantee + hint-coverage guard tests (every command ends with one footer; every reachable rule_key has a hint; deterministic, no new side effects).
+
+### Changed
+
+- Footer-rendering machinery promoted from `commands/pr/` into `core/` (pure relocation; pr footers byte-identical).
+- `gamify` now emits the structured footer for install/uninstall, replacing the prior ad-hoc `Next:` line.
+
+### Fixed
+
+- `gamify` unsupported-backend notice (codex/copilot/acp) now ends with a `Next step:` footer, closing a gap in the cross-command guarantee.
+
+## [0.26.1] - 2026-05-29
+
+### Added
+
+- SonarCloud CI-based analysis + coverage upload: a `sonarcloud` job in test.yml runs `pytest --cov` and the SHA-pinned `sonarqube-scan-action` (v6), reading `sonar-project.properties` + the `SONAR_TOKEN` secret. Coverage config lives in `pyproject.toml [tool.coverage.run]` (`relative_files` so coverage.xml paths map to `sonar.sources=src`).
+
+### Changed
+
+- SonarCloud moved from Automatic Analysis to CI-based analysis (the two are mutually exclusive); project now under the `agentculture` org. Updated CLAUDE.md / sonar-project.properties notes accordingly.
+
 ## [0.26.0] - 2026-05-29
 
 ### Added

{agex_cli-0.26.0 → agex_cli-0.27.0}/CLAUDE.md

@@ -38,9 +38,13 @@ cli.py ──► commands/<name>/scripts/<name>.py ──► core/render.py
 
 - `cli.py` (Typer) routes `devex <command> [args] --agent X`. No business logic.
 - Each `commands/<name>/` is a **skill-folder**: `SKILL.md` + `scripts/` + `assets/` + `references/`. The `SKILL.md` doubles as the content emitted by `devex explain <command>`.
-- `core/` is shared plumbing — backend enum, `.devex/` paths, Jinja renderer (`StrictUndefined`), TOML config, SKILL.md frontmatter parser, capability matrix loader, hook JSON I/O. Command- and content-agnostic.
+- `core/` is shared plumbing — backend enum, `.devex/` paths, Jinja renderer (`StrictUndefined`), TOML config, SKILL.md frontmatter parser, capability matrix loader, hook JSON I/O, footer renderer (`core/footer.py`). Command- and content-agnostic.
 - A backend lives in three places: `core/backend.Backend` (enum entry), `backends/<name>/probe.py` (optional Python probe), and one YAML per relevant command under `commands/*/assets/backends/<name>.yaml`. Adding a backend touches only those locations.
 
+## Cross-command "Next step:" footers (v0.27.0+)
+
+Every non-silent command ends with a deterministic, per-backend **"Next step:"** footer — an agent-facing micro-prompt telling the running agent how to continue. The renderer is shared in `core/footer.py`: `render_footer(rule_key, backend, context, backends_pkg)` (backend path) and `render_neutral_footer(rule_key, context)` (no-backend path; hints from `core/assets/backends/neutral.yaml`); the block template is `core/assets/footer.md.j2` (`---\n**Next step:** <hint>`). Each command supplies a decision function (`commands/<cmd>/scripts/next_step.py`, returns `(rule_key, context)`) and per-backend `hints:` under `commands/<cmd>/assets/backends/<backend>.yaml`. `explain` and `doctor` take an **optional** `--agent` (backend footer when given, neutral when omitted; flagless calls unchanged). `hook write` stays **silent** (no footer) — the deliberate exception. Two guard tests enforce the guarantee: `tests/test_footer_guarantee.py` (every command ends with exactly one footer; deterministic; no new side effects) and `tests/test_footer_hints.py` (every reachable `(command, backend, rule_key)` has a hint; hints are agent-imperative).
+
 ## `devex pr` namespace (v0.17.0+)
 
 `lint`, `open`, `read`, `reply`, `review`, `await`, `delta`. Each command ends with a deterministic "Next step:" footer. The `pr` namespace allows scoped network I/O (via `gh`) and bounded `--wait` sleep — a deliberate carve-out from the no-network/no-sleep invariants. `pr open` (non-draft, new PR) and `pr review` post the Qodo `/agentic_review` trigger comment; the legacy `/improve` is deprecated and never emitted. The trigger string lives in one place: `commands/pr/scripts/review.QODO_REVIEW_TRIGGER`. `pr await --detach` / `--check` (issue #64) move the bounded poll out of the agent session: `--detach` forks a detached worker (`commands/pr/scripts/_await_worker.py`) that writes the verdict to a marker (`commands/pr/scripts/_detach.py`, atomic `os.replace`), and `--check` reads it back without sleeping. Key modules:
@@ -78,15 +82,15 @@ uv run devex --version
 uv run devex explain devex
 uv run devex explain explain
 
-# Coverage (matches what build.yml runs; SonarCloud reads this file)
+# Coverage (matches the `sonarcloud` job in test.yml; SonarCloud reads coverage.xml)
 uv run pytest --cov=src/devex --cov-report=xml --cov-report=term
 ```
 
 ## CI surface
 
-- `.github/workflows/test.yml` — matrix: 3 OS × 4 Python (3.10–3.13) running `uv run pytest`. Also runs a `version-check` job on PRs that fails (with a sticky `<!-- version-check -->` comment) when `pyproject.toml`'s version on the PR matches the one on `main` and any code file under `src/` / `tests/` / `pyproject.toml` changed. Docs-only PRs skip the check.
+- `.github/workflows/test.yml` — matrix: 3 OS × 4 Python (3.10–3.13) running `uv run pytest`. Also runs (1) a `sonarcloud` job that generates `coverage.xml` (`pytest --cov`, repo-relative paths via `pyproject [tool.coverage.run]`) and runs the SHA-pinned `sonarqube-scan-action` (needs the `SONAR_TOKEN` repo secret); and (2) a `version-check` job on PRs that fails (with a sticky `<!-- version-check -->` comment) when `pyproject.toml`'s version on the PR matches the one on `main` and any code file under `src/` / `tests/` / `pyproject.toml` changed. Docs-only PRs skip the version check.
 - `.github/workflows/publish.yml` — builds sdist + wheel. PRs publish a per-PR dev version to TestPyPI (sticky install-command comment); pushes to `main` publish the stable version to TestPyPI (canary), then an `autotag` job pushes `v<version>` if missing, which gates the inline `publish-pypi` + `github-release` jobs. No manual tagging — bumping `pyproject.toml` is the release signal.
-- SonarCloud is configured as **Automatic Analysis** on the repo (no CI workflow). Coverage and quality are read by SonarCloud directly.
+- SonarCloud runs in **CI-based analysis** mode (Automatic Analysis is off — the two are mutually exclusive). The `sonarcloud` job in `test.yml` uploads coverage + triggers the scan via `sonarqube-scan-action`, reading `sonar-project.properties` and the `SONAR_TOKEN` secret. The quality gate decorates PRs and gates merges.
 - All third-party actions are **pinned to full commit SHAs** with trailing `# vN` comments (rule `githubactions:S7637`). Keep new actions pinned the same way.
 
 ## SonarCloud notes

{agex_cli-0.26.0 → agex_cli-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agex-cli
-Version: 0.26.0
+Version: 0.27.0
 Summary: Agent-operated developer-experience CLI — deterministic per-backend markdown briefings for autonomous agents.
 Project-URL: Homepage, https://culture.dev/devex/
 Project-URL: Repository, https://github.com/agentculture/devex