devex-cli 0.31.0__tar.gz → 0.32.0__tar.gz

{devex_cli-0.31.0 → devex_cli-0.32.0}/.claude/skills/recall/SKILL.md

@@ -81,7 +81,7 @@ Every `recall` hit carries a `signal` field (float in `[0, 1]`). The signal
 blends **multiplicatively** into the lexical/vector score so recently-created
 and frequently-recalled records surface ahead of stale ones. The formula:
 
-```
+```text
 access_bonus = min(0.5, recall_count * 0.05)
 age_factor   = 1 / (1 + days_since_creation * 0.01)
 staleness    = days_since_last_recall * 0.01

devex_cli-0.32.0/.devague/frames/devex-now-closes-the-developer-experience-loop-it.json

@@ -0,0 +1,268 @@
+{
+  "slug": "devex-now-closes-the-developer-experience-loop-it",
+  "title": "devex now closes the developer-experience loop: it measures coverage, learns from the agent's tracked performance, turns that learning into advice, structures work into assessable units, and lets an agent run non-touch \u2014 assess, decide where it can, and continue \u2014 with full introspection for humans and agents.",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-07-01T23:37:04Z",
+  "updated": "2026-07-01T23:52:19Z",
+  "claims": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "devex now closes the developer-experience loop: it measures coverage, learns from the agent's tracked performance, turns that learning into advice, structures work into assessable units, and lets an agent run non-touch \u2014 assess, decide where it can, and continue \u2014 with full introspection for humans and agents.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h7",
+          "text": "One release demonstrates the full loop in this repo: a coverage measurement exists, a deterministic aggregation learns from it, an advice briefing renders it, and an agent continues from it non-touch \u2014 each step verified by tests",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [
+        {
+          "id": "q1",
+          "text": "Is this one shippable feature or a roadmap of five or six? What is the smallest slice that proves the loop closes (measure, learn, advise, continue)?",
+          "resolved": false,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "Autonomous coding agents operating devex day-to-day, and the humans supervising them who need introspection into what the agent did and why",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h8",
+          "text": "The slice serves both audiences concretely: the agent consumes the briefing mid-session to pick its next move, and a human can read the same markdown after the fact and understand what happened and why",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c3",
+      "kind": "before_state",
+      "text": "devex briefs and advises per command (footers, lessons, gamify hooks) but nothing closes the loop: hook events are written yet barely read back, advice is static per-backend YAML, and an agent still stops for a human between steps",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h9",
+          "text": "The before-state is verifiable in today's code: hook events are written but only hook read renders them (no shipped command aggregates them into advice), and footer hints are static per-backend YAML",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c4",
+      "kind": "after_state",
+      "text": "An agent runs a work session end-to-end non-touch: devex tells it what is covered and what is not, learns from its tracked performance, advises the next move, and the agent assesses, decides where it can, and continues \u2014 while humans can introspect the whole trail",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h1",
+          "text": "A full non-touch cycle is demonstrable in this repo: the agent uses only devex output (footers, advice, briefings) to pick each next step, with no human prompt between starting work and merge-readiness",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [
+        {
+          "id": "q2",
+          "text": "Where is the line between 'decides where it can' and decisions that must stay with the human \u2014 who defines that policy, devex or the agent's own skill?",
+          "resolved": false,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "Agent time is cheapest when uninterrupted \u2014 every unnecessary human touch is a stall; deterministic advice grounded in the agent's own usage data raises quality without adding LLM calls",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h10",
+          "text": "The value claim costs nothing to honor: the advice path adds zero LLM calls and no new side-effect classes (pure reads), so any quality gain is free at runtime",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "devex stays a non-agentic deterministic-markdown CLI: no LLM calls, no auto-detection, markdown only; 'learning' means deterministic aggregation of tracked events, never model inference; devex advises the next move but never executes it",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h2",
+          "text": "Every 'learning' or 'advice' output is reproducible byte-for-byte from the same event journal \u2014 deterministic aggregation, no LLM call, verified by a guard test like the footer guarantee",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c7",
+      "kind": "success_signal",
+      "text": "An agent completes a branch-to-merge-ready cycle with zero human touches except final review, and devex can show from tracked events what it advised and what the agent actually did",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h3",
+          "text": "The introspection trail exists as a readable artifact: devex can render what it advised at each step and what event followed, from .devex/data alone",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c8",
+      "kind": "assumption",
+      "text": "The existing hook event stream (devex hook write/read) is rich enough to learn performance from, or can be extended cheaply",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h4",
+          "text": "A concrete list exists of which decisions the advice layer needs to make and which event fields each one requires \u2014 and the gap between that and today's hook schema is enumerated",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c9",
+      "kind": "open_question",
+      "text": "Whether 'coverage' means test-coverage briefings, command-by-backend capability coverage, or usage coverage of devex features by the agent",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c10",
+      "kind": "decision",
+      "text": "Coverage means three surfaces: usage coverage (which devex features the agent exercises, from hook events), test-coverage briefings (the project's coverage surfaced to the agent), and capability coverage (command-by-backend matrix). Raising devex's own repo test coverage is NOT this feature.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c11",
+      "kind": "decision",
+      "text": "Scope is one release with a single loop-closing slice proving measure, learn, advise, continue; each of the six threads contributes only what that slice needs, the rest parks as follow-ups.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c12",
+      "kind": "decision",
+      "text": "Performance learning is layered: start with deterministic aggregation of already-tracked usage events, then extend the schema toward work outcomes (PR cycles, review findings) already journaled under .devex/data/pr/.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c13",
+      "kind": "requirement",
+      "text": "The slice reads only existing or adjacent data sources \u2014 the .devex/data journals, the capability matrix, and the project's coverage report when present \u2014 and emits one deterministic markdown briefing telling the agent what is unused, untested, or unsupported, plus the recommended next move",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h5",
+          "text": "With an empty journal, no coverage report, and a bare repo, the briefing still renders exit-0 with a useful notice (unsupported-is-success); with fixed inputs it is byte-for-byte reproducible",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c14",
+      "kind": "requirement",
+      "text": "The slice's output composes with the existing Next-step footer system so a non-touch agent can chain from any command into the advice loop and back to work without a human prompt",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h6",
+          "text": "A guard test proves the advice output ends with exactly one Next-step footer, and at least one existing command's footer routes into the advice loop",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c15",
+      "kind": "decision",
+      "text": "devex never encodes the human-vs-agent decision policy: it emits advice; the agent's harness owns which decisions need human sign-off",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c16",
+      "kind": "decision",
+      "text": "For this slice, structured work is emergent (footers + journal + advice loop); a dedicated work/session noun parks as a follow-up",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c17",
+      "kind": "non_goal",
+      "text": "No new side-effect classes: the slice is read-only (journal reads, matrix reads, coverage-report reads); it does not write state, spawn processes, or open sockets",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    }
+  ],
+  "open_vagueness": [
+    {
+      "id": "v1",
+      "text": "Exact aggregation schema for performance metrics (what counts as a measurement unit: command invocations, PR cycles, review findings, time-to-merge)",
+      "kind": "unknown_nonblocking",
+      "claim_id": null
+    },
+    {
+      "id": "v2",
+      "text": "Whether 'structured work' needs a new noun (e.g. devex work / session) or is an emergent property of footers plus journal",
+      "kind": "follow_up",
+      "claim_id": null
+    }
+  ]
+}

devex_cli-0.32.0/.devague/plans/devex-now-closes-the-developer-experience-loop-it.json

@@ -0,0 +1,287 @@
+{
+  "slug": "devex-now-closes-the-developer-experience-loop-it",
+  "title": "devex now closes the developer-experience loop: it measures coverage, learns from the agent's tracked performance, turns that learning into advice, structures work into assessable units, and lets an agent run non-touch \u2014 assess, decide where it can, and continue \u2014 with full introspection for humans and agents.",
+  "frame_slug": "devex-now-closes-the-developer-experience-loop-it",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-07-01T23:53:26Z",
+  "updated": "2026-07-01T23:57:26Z",
+  "targets": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "devex now closes the developer-experience loop: it measures coverage, learns from the agent's tracked performance, turns that learning into advice, structures work into assessable units, and lets an agent run non-touch \u2014 assess, decide where it can, and continue \u2014 with full introspection for humans and agents."
+    },
+    {
+      "id": "h7",
+      "kind": "honesty",
+      "text": "One release demonstrates the full loop in this repo: a coverage measurement exists, a deterministic aggregation learns from it, an advice briefing renders it, and an agent continues from it non-touch \u2014 each step verified by tests"
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "Autonomous coding agents operating devex day-to-day, and the humans supervising them who need introspection into what the agent did and why"
+    },
+    {
+      "id": "h8",
+      "kind": "honesty",
+      "text": "The slice serves both audiences concretely: the agent consumes the briefing mid-session to pick its next move, and a human can read the same markdown after the fact and understand what happened and why"
+    },
+    {
+      "id": "c3",
+      "kind": "before_state",
+      "text": "devex briefs and advises per command (footers, lessons, gamify hooks) but nothing closes the loop: hook events are written yet barely read back, advice is static per-backend YAML, and an agent still stops for a human between steps"
+    },
+    {
+      "id": "h9",
+      "kind": "honesty",
+      "text": "The before-state is verifiable in today's code: hook events are written but only hook read renders them (no shipped command aggregates them into advice), and footer hints are static per-backend YAML"
+    },
+    {
+      "id": "c4",
+      "kind": "after_state",
+      "text": "An agent runs a work session end-to-end non-touch: devex tells it what is covered and what is not, learns from its tracked performance, advises the next move, and the agent assesses, decides where it can, and continues \u2014 while humans can introspect the whole trail"
+    },
+    {
+      "id": "h1",
+      "kind": "honesty",
+      "text": "A full non-touch cycle is demonstrable in this repo: the agent uses only devex output (footers, advice, briefings) to pick each next step, with no human prompt between starting work and merge-readiness"
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "Agent time is cheapest when uninterrupted \u2014 every unnecessary human touch is a stall; deterministic advice grounded in the agent's own usage data raises quality without adding LLM calls"
+    },
+    {
+      "id": "h10",
+      "kind": "honesty",
+      "text": "The value claim costs nothing to honor: the advice path adds zero LLM calls and no new side-effect classes (pure reads), so any quality gain is free at runtime"
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "devex stays a non-agentic deterministic-markdown CLI: no LLM calls, no auto-detection, markdown only; 'learning' means deterministic aggregation of tracked events, never model inference; devex advises the next move but never executes it"
+    },
+    {
+      "id": "h2",
+      "kind": "honesty",
+      "text": "Every 'learning' or 'advice' output is reproducible byte-for-byte from the same event journal \u2014 deterministic aggregation, no LLM call, verified by a guard test like the footer guarantee"
+    },
+    {
+      "id": "c7",
+      "kind": "success_signal",
+      "text": "An agent completes a branch-to-merge-ready cycle with zero human touches except final review, and devex can show from tracked events what it advised and what the agent actually did"
+    },
+    {
+      "id": "h3",
+      "kind": "honesty",
+      "text": "The introspection trail exists as a readable artifact: devex can render what it advised at each step and what event followed, from .devex/data alone"
+    },
+    {
+      "id": "c13",
+      "kind": "requirement",
+      "text": "The slice reads only existing or adjacent data sources \u2014 the .devex/data journals, the capability matrix, and the project's coverage report when present \u2014 and emits one deterministic markdown briefing telling the agent what is unused, untested, or unsupported, plus the recommended next move"
+    },
+    {
+      "id": "h5",
+      "kind": "honesty",
+      "text": "With an empty journal, no coverage report, and a bare repo, the briefing still renders exit-0 with a useful notice (unsupported-is-success); with fixed inputs it is byte-for-byte reproducible"
+    },
+    {
+      "id": "c14",
+      "kind": "requirement",
+      "text": "The slice's output composes with the existing Next-step footer system so a non-touch agent can chain from any command into the advice loop and back to work without a human prompt"
+    },
+    {
+      "id": "h6",
+      "kind": "honesty",
+      "text": "A guard test proves the advice output ends with exactly one Next-step footer, and at least one existing command's footer routes into the advice loop"
+    }
+  ],
+  "tasks": [
+    {
+      "id": "t1",
+      "summary": "Usage-coverage aggregation: deterministic module (commands/advise/scripts/_usage.py) that reads the .devex/data event journal and derives per-command counts, unused commands (vs the CLI's own command registry, not a hardcoded list), and last activity",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "Given a fixed fixture journal, the aggregation result is identical across runs (test asserts equality of rendered output)",
+        "An empty or missing journal yields a well-formed 'no usage data yet' result with exit 0, not an error",
+        "The unused-command list is derived from the argparse command registry so a future command appears without editing the module"
+      ],
+      "deps": [],
+      "covers": [
+        "c3",
+        "h9",
+        "c13",
+        "h2"
+      ]
+    },
+    {
+      "id": "t2",
+      "summary": "Test-coverage briefing reader: parse the project's coverage report (Cobertura coverage.xml) when present into overall percentage plus the N least-covered files (commands/advise/scripts/_coverage.py, stdlib XML only)",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "A fixture coverage.xml produces a deterministic summary (overall %, least-covered files) across runs",
+        "Absent or malformed coverage.xml renders an unsupported-is-success notice section, exit 0"
+      ],
+      "deps": [],
+      "covers": [
+        "c13",
+        "h5"
+      ]
+    },
+    {
+      "id": "t3",
+      "summary": "Capability-coverage section: from the existing capability matrix, render which commands are supported/unsupported for the given backend (commands/advise/scripts/_capability.py)",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "For each of the four backends the section lists supported and unsupported commands consistent with core/capabilities.py",
+        "Output is deterministic and matrix-driven \u2014 no hardcoded command names"
+      ],
+      "deps": [],
+      "covers": [
+        "c13"
+      ]
+    },
+    {
+      "id": "t4",
+      "summary": "The devex advise command: new skill-folder (commands/advise/ with SKILL.md, scripts/advise.py, assets/templates/advise.md.j2) + cli.py routing with required --agent; composes the usage, test-coverage, and capability sections into one deterministic markdown briefing ending in a recommended next move",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "uv run devex advise --agent claude-code renders one briefing with usage-coverage, test-coverage, and capability-coverage sections plus a recommended next move",
+        "In a bare repo (no journal, no coverage.xml) the briefing still renders exit 0 with useful unsupported-is-success notices per section",
+        "devex explain advise renders the SKILL.md (skill-folder contract holds)"
+      ],
+      "deps": [
+        "t1",
+        "t2",
+        "t3"
+      ],
+      "covers": [
+        "c1",
+        "c4",
+        "c13",
+        "h5"
+      ]
+    },
+    {
+      "id": "t5",
+      "summary": "Footer wiring both directions: advise gets scripts/next_step.py + hints for all four backends (assets/backends/{claude-code,codex,copilot,acp}.yaml), and at least one existing command's footer (hook read and overview) routes into devex advise",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "tests/test_footer_guarantee.py passes with advise included: exactly one deterministic footer, no new side effects",
+        "tests/test_footer_hints.py passes: every reachable (advise, backend, rule_key) has an agent-imperative hint",
+        "hook read's and overview's footers recommend devex advise under a deterministic rule (e.g. when tracked events exist)"
+      ],
+      "deps": [
+        "t4"
+      ],
+      "covers": [
+        "c14",
+        "h6",
+        "c4"
+      ]
+    },
+    {
+      "id": "t6",
+      "summary": "Introspection trail: a briefing section (and/or hook read enhancement) rendering, from .devex/data alone, the recent event sequence with the advice that applied at each step \u2014 readable by a human after the fact",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "Given a fixture journal, the trail renders each event with the advised next move that followed, in plain human-readable markdown",
+        "The trail is derived from .devex/data alone \u2014 test runs with network and subprocess access stubbed out"
+      ],
+      "deps": [
+        "t4"
+      ],
+      "covers": [
+        "c2",
+        "h8",
+        "c7",
+        "h3"
+      ]
+    },
+    {
+      "id": "t7",
+      "summary": "Determinism and read-only guard tests for the advise path: prove the boundary holds \u2014 zero LLM calls, no new side-effect classes, byte-for-byte reproducible output",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "A test proves advise output is byte-for-byte identical across two runs over the same fixture inputs",
+        "A test proves advise writes nothing (filesystem snapshot of .devex unchanged), spawns no subprocess, and opens no socket"
+      ],
+      "deps": [
+        "t4"
+      ],
+      "covers": [
+        "c5",
+        "h10",
+        "c6",
+        "h2"
+      ]
+    },
+    {
+      "id": "t8",
+      "summary": "Non-touch loop demo + docs: a walkthrough (docs/) of the closed loop and an integration test that walks the footer chain \u2014 every recommended next command exists, runs exit 0, and the chain reaches advise and returns to work without human input",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "An integration test follows footers from overview through hook read into advise and asserts each recommended command parses and runs exit 0 against a fixture repo",
+        "A docs walkthrough shows the full cycle (measure, learn, advise, continue) with real command output, readable by agent and human",
+        "CLAUDE.md and README gain an advise section consistent with the shipped behavior"
+      ],
+      "deps": [
+        "t5",
+        "t6",
+        "t7"
+      ],
+      "covers": [
+        "c1",
+        "h7",
+        "h1",
+        "c7",
+        "c4",
+        "c2"
+      ]
+    },
+    {
+      "id": "t9",
+      "summary": "Release mechanics: version-bump minor in pyproject.toml, CHANGELOG entry, full suite green (uv run pytest), PR via devex pr open",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "version-check CI job passes (pyproject version differs from main; CHANGELOG has the new section)",
+        "Full test suite passes locally before the PR opens"
+      ],
+      "deps": [
+        "t8"
+      ],
+      "covers": []
+    }
+  ],
+  "risks": [
+    {
+      "id": "r1",
+      "text": "Cobertura coverage.xml is the assumed coverage format; lcov / .coverage-SQLite readers are follow-ups",
+      "kind": "follow_up",
+      "task_id": null
+    },
+    {
+      "id": "r2",
+      "text": "Outcome-layer learning (PR cycles, review findings from .devex/data/pr/) is the decided second layer \u2014 explicitly not in this slice",
+      "kind": "follow_up",
+      "task_id": null
+    },
+    {
+      "id": "r3",
+      "text": "A dedicated work/session noun for structured work parked as follow-up in the frame (v2); revisit after the slice ships",
+      "kind": "follow_up",
+      "task_id": null
+    }
+  ]
+}

{devex_cli-0.31.0 → devex_cli-0.32.0}/.gitignore

@@ -211,6 +211,12 @@ __marimo__/
 .devex/data/
 .agex/data/
 
+# Test fixtures deliberately named coverage.xml (commands/advise's
+# test-coverage reader, tests/commands/advise/test_coverage.py) -- un-ignore
+# despite the blanket `coverage.xml` rule above, which is meant only for the
+# real build artifact at the repo root.
+!tests/fixtures/coverage/**/coverage.xml
+
 # Worktrees
 .worktrees/
 

{devex_cli-0.31.0 → devex_cli-0.32.0}/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.32.0] - 2026-07-02
+
+### Added
+
+- `devex advise` — the loop-closing briefing: usage coverage (journal aggregation vs the CLI registry), test-coverage briefing (Cobertura coverage.xml reader), capability coverage (per-backend matrix flags), an introspection trail (recent events + the advice that applied, from .devex/data alone), and a recommended next move — deterministic, read-only, zero LLM calls, with per-backend Next-step footers for all four backends
+- Footer routing into the advice loop: `hook read` (events present, rule `hook_read_advise`) and `overview` (project configured, rule `overview_advise`) now recommend `devex advise`
+- Non-touch loop integration test (`tests/test_advise_loop.py`) walking the footer chain overview → advise → gamify → learn, plus determinism/read-only guard tests (`tests/commands/advise/test_guarantees.py`)
+- Docs: `docs/advise-loop.md` walkthrough (measure → learn → advise → continue), CLAUDE.md + README sections; spec + plan under `docs/specs/` / `docs/plans/` (devague frame `devex-now-closes-the-developer-experience-loop-it`)
+
+### Fixed
+
+- `.gitignore`: narrow negation so `tests/fixtures/coverage/**/coverage.xml` fixtures are trackable despite the blanket `coverage.xml` rule
+- Usage/trail readers under `devex advise` no longer crash on a stray or non-slug file under `.devex/data` (`ValueError` from the stream-name validator is now skipped) or on an unreadable/non-UTF-8 journal file (`core._jsonl.load_lines` degrades to `[]` on `OSError`/`UnicodeDecodeError`), preserving the command's read-only, always-exit-0 contract
+
 ## [0.31.0] - 2026-06-23
 
 ### Added
@@ -25,8 +41,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   eidetic-cli checkout with `uv`). Propagated by rollout-cli's `eidetic-memory`
   recipe.
 
-## [Unreleased]
-
 ## [0.30.1] - 2026-06-19
 
 ### Added

{devex_cli-0.31.0 → devex_cli-0.32.0}/CLAUDE.md

@@ -72,6 +72,19 @@ Spec: `docs/superpowers/specs/2026-05-10-agex-pr-design.md`. Plan: `docs/superpo
 
 Spec: `docs/specs/2026-06-19-devex-now-reads-qodo-pr-review-findings-structural.md`. Plan: `docs/plans/2026-06-19-devex-now-reads-qodo-pr-review-findings-structural.md`.
 
+## `devex advise` — the loop-closing briefing (v0.31.0+)
+
+`devex advise --agent <backend>` closes the developer-experience loop: it **measures** three coverage surfaces, **learns** from the agent's tracked usage (deterministic aggregation — never model inference), **advises** one next move, and its footer lets the agent **continue** non-touch. One deterministic markdown briefing, read-only, zero LLM calls. Skill-folder: `commands/advise/` (`SKILL.md` + `scripts/advise.py` + `assets/templates/advise.md.j2`), routed in `cli.py` with a required `--agent`.
+
+- **Three coverage surfaces** (the section headings, in order): **Usage coverage** (`scripts/_usage.py` — which devex commands the agent has exercised, from the `.devex/data` journal; the command set is introspected from the CLI's own argparse registry via `registry_commands()`, never hardcoded), **Test coverage** (`scripts/_coverage.py` — Cobertura `coverage.xml` overall line-rate + least-covered files, stdlib XML only), and **Capability coverage** (`scripts/_capability.py` — supported/unsupported capability flags for the backend, from `core/capabilities.py`). Raising devex's *own* repo test coverage is explicitly not this feature.
+- **The introspection trail** (`scripts/_trail.py`, t6) — a fourth section replaying the recent event sequence with the *usage-only* advice that applied at each step, from `.devex/data` alone (h3: a human-readable after-the-fact record). It replays only the usage-only slice because test-coverage state is never journaled event-by-event; the live decision and the trail share one `usage_only_next_step()` so "what usage says" can't be defined two ways.
+- **One decision, consumed twice.** `scripts/next_step.py:advise_next_step(usage, coverage)` returns the single `(rule_key, context)` that drives both the in-body "Recommended next move" line and the trailing "Next step:" footer, so they can't diverge. Rule keys (`RULE_KEYS`, priority order): `no_tracking` (empty journal → install tracking via `gamify`), `unused_commands` (some commands never exercised → try one; `example` is the first unused command other than `advise` itself), `no_coverage` (usage complete but no `coverage.xml`), `all_covered` (nothing flagged). Per-backend footer phrasing under `commands/advise/assets/backends/<backend>.yaml`; body/trail phrasing beside the decision in `next_step.py`.
+- **Routing into advise (both directions closed).** `hook read`'s footer (`hook_read_advise`) routes into `devex advise` once events are tracked, and `overview`'s footer (`overview_advise`) routes into it once the project is configured — so an agent chains overview/hook-read → advise → next command with no human prompt. The non-touch chain is proven executably by `tests/test_advise_loop.py` (walks footers overview → advise → gamify → learn → …, each hop exit 0 + exactly one footer) plus the doc walkthrough `docs/advise-loop.md`.
+- **Boundary — read-only, adds NO new side-effect class.** advise reads the journal, matrix, and `coverage.xml`; it writes nothing, spawns nothing, opens no socket, and deliberately does **not** call `ensure_init()` (reading usage must never create `.devex/`). Empty journal / missing coverage / bare repo all render exit 0 with per-section unsupported-is-success notices (invariant #5). Output is byte-for-byte reproducible (guard tests in `tests/commands/advise/test_guarantees.py`). Because it is pure-read, the "Side effects only in …" invariant above is unchanged.
+- **Out of scope (parked follow-ups).** Outcome-layer learning (PR cycles / review findings under `.devex/data/pr/`) is the decided *second* layer, not this slice; non-Cobertura coverage readers (lcov, `.coverage` SQLite) are follow-ups; a dedicated `work` / `session` noun for structured work stays a follow-up (structured work is emergent from footers + journal + advise for now).
+
+Spec: `docs/specs/2026-07-01-devex-now-closes-the-developer-experience-loop-it.md`. Plan: `docs/plans/2026-07-01-devex-now-closes-the-developer-experience-loop-it.md`.
+
 ## Conventions worth following
 
 - **Resource loading: use `importlib.resources.files(...)` and treat the result as a `Traversable`.** Call `.joinpath()` / `.is_file()` / `.read_text(encoding="utf-8")` directly. Wrap with `importlib.resources.as_file()` only when a third-party API needs a real `pathlib.Path`. Do NOT do `Path(str(files(...)))` — it's not zipapp/PEX safe.