akm-cli 0.9.27 → 0.9.28-alpha.2

package/CHANGELOG.md

@@ -6,6 +6,71 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.28-alpha.2] - 2026-10-08
+
+### Added
+
+- **`akm metrics` (experimental) reports what akm has recorded, in every `--format`.** One
+  read-only command covers asset usage (searches, shows, curates, selects, the
+  queries that returned nothing), feedback with its reasons and tags, utility
+  and outcome scores, LLM tokens, latency, task runs,
+  proposals and workflow token spend. `--since` (default `30d`) sets the window start; the window ends now, counts
+  `user`-source usage and keeps the top 20 of every ranked list. The
+  window rows (usage rows as recorded, LLM calls summed per day, engine, model, process and stage) ride along with
+  `--format html` and `--detail full`. A window
+  longer than a store's retention says so in `notes`.
+
+- **`akm metrics` renders as text and Markdown.** `--format text` prints aligned
+  Usage, Feedback, Utility, LLM, Index, Tasks, Proposals and Workflows sections
+  with top-N tables (cut to 5 at `--detail brief`); `--format md` prints one
+  heading per section with GFM tables.
+
+- **`akm metrics --format html` writes a self-contained dashboard.** The page
+  carries the window's raw rows, so you can filter by date, bundle, source and
+  event type, sort the tables, open an asset to see its timeline, queries and
+  feedback, and download any table as CSV, all in the browser. Charts load
+  ECharts from the same CDN tag as `akm health --report`. A page keeps the most
+  recent 50,000 usage rows and says so when it cuts older ones.
+
+### Changed
+
+- **LLM usage is recorded for every command.** `akm index`, curate, workflow,
+  agent dispatch and `akm command run` now persist their `llm_usage` events
+  like `improve` and `proposal drain` already did; before, a call made outside
+  those two was dropped. An improve run still keeps its own sink and the
+  process-wide one resumes when it ends.
+
+- Search latency is recorded in the search summary usage row (`totalMs`, plus `rankMs` and `embedMs` when present), and every `akm index` run appends an `index_completed` event with its phase timings.
+
+### Fixed
+
+- **Usage-event retention no longer deletes a day early.** The purge on `akm index`
+  compared the space-separated `created_at` against an ISO cutoff, so every row on
+  the cutoff's date was removed up to 24 hours before its 90 days were up. Both
+  sides are now normalized before the comparison.
+
+## [0.9.28-alpha.1] - 2026-10-08
+
+### Fixed
+
+- **Distill skips a memory marked `beliefState: deprecated` or `superseded`.** Such a note is no longer true and gave
+  no lesson (26 of about 900 memories carry the state; distill ran on 17 of them). The improve loop records a
+  `distill-skipped` action and an `improve_skipped` event (`distill_deprecated_or_superseded`), and the attempt goes
+  in the ledger as `unchanged`; an explicit `--scope` ref still runs. `contradicted` is still distilled.
+- The distill judge scores a lesson 1–2 on non-redundancy when a listed asset
+  states most of what it says, not only when it states the same rule, and is
+  told to compare only with the listed assets, never with the source memory.
+  Before, a lesson that restated a skill the library holds scored 3 ("largely
+  redundant") and went to a reviewer. Judge-only replay of the lessons the
+  writer produced (local qwen3.8-27b, 3 repeats): of 4 public lessons for
+  memories that deserve none, 12 verdicts passed 3 before and 1 after, and of
+  12 such own lessons 33 of 36 passed before and 27 after, while the 31
+  lesson-worthy own lessons lost no verdict (2 of 93 rejected before, 0 after).
+- **The pair judge's reason no longer swaps A and B.** In a replay of 120 recorded pairs, 18 of 90 retirement
+  reasons said the opposite of what the judge's claim lists decided (for example "B contains all claims from A" for a
+  pair where B was retired). The lists were right, so no retirement changed, but the reason a reviewer reads was
+  wrong. The prompt now asks the reason to name the asset that can be deleted; two replays gave 0 and 1 of about 85.
+
 ## [0.9.27] - 2026-10-07
 
 The stable release of the 0.9.27 line: 0.9.27-alpha.1, alpha.2 and alpha.3.

package/STABILITY.md

@@ -46,6 +46,7 @@ enumeration of the whole `proposal` noun group.
 | `akm setup` | Stable | |
 | `akm index` | Stable | |
 | `akm health` | Evolving | Exit codes are Evolving; report *content* and rendered `md`/`html` layout are Experimental — do not script against report layout. |
+| `akm metrics` | Experimental | New in 0.9.28. Report content, JSON shape and the `html` dashboard may change. |
 | `akm info` | Stable | |
 | `akm bundle create` | Stable | |
 | `akm bundle add` | Stable | |
@@ -341,6 +342,9 @@ CHANGELOG with a migration note.
 Subject to change without notice within minor releases. Not yet recommended
 for scripted use.
 
+- **`akm metrics`** — new in 0.9.28. What it reports, its JSON shape and the
+  `--format html` dashboard may change in any release; do not script against
+  them.
 - **`lesson` asset type** — schema (`when_to_use`, `description`) is
   stable, but lesson-distillation triggers and ranking are tuning targets.
 - **`--shape agent` and `--shape summary`** — the output-projection axis

package/dist/assets/hints/cli-hints-full.md

@@ -416,6 +416,9 @@ akm agent --model sonnet --prompt "..."         # Model override (aliases or exa
 akm info                                       # Capabilities, bundle dir, index stats, semantic-search status
 akm health                                     # Runtime diagnostics; exit 0 ok / 4 warn / 1 fail
 akm health --report                            # Adds accept-rate metrics
+akm metrics                                    # Usage, feedback, utility, LLM tokens, tasks, workflows (last 30d, read-only)
+akm metrics --since 7d                         # Narrow the window
+akm metrics --format html --output metrics.html # Self-contained dashboard with the window's rows (filter, sort, export CSV)
 akm log                                        # Append-only event stream (mutations, feedback, indexing)
 akm log --ref <ref>                            # One asset's event trail
 akm log --since @offset:<id>                   # Durable row-id cursor — poll this to follow the stream

package/dist/assets/hints/cli-hints-short.md

@@ -47,6 +47,7 @@ akm clone <ref>                               # Copy an asset to the working bun
 akm sync                                      # Commit (and push if writable remote) changes in the primary bundle (--no-push to commit only)
 akm improve --no-sync                         # Run improve without the end-of-run auto-commit
 akm improve --no-push                         # Auto-commit but skip push for this run
+akm metrics --since 7d                        # What was searched, shown and rated, and which assets went unused (--format html: dashboard)
 akm search "<query>" --from registry          # Search all registries (registry search was folded into search)
 ```
 

package/dist/assets/prompts/consolidate-pair.md

@@ -16,4 +16,4 @@ Then classify the relation as exactly one of:
 
 Set "redundant" to the asset that could be deleted with no loss: "A" for "duplicate", the asset with the empty list for "subsumed", "A" for "supersedes"; else null. Set "stale" to "A" when the relation is "supersedes", else null.
 
-Answer ONLY with JSON: {"onlyInA": ["..."], "onlyInB": ["..."], "relation": "...", "redundant": "A"|"B"|null, "stale": "A"|null, "confidence": 0.0-1.0, "reason": "<at most 25 words>"}
+Answer ONLY with JSON: {"onlyInA": ["..."], "onlyInB": ["..."], "relation": "...", "redundant": "A"|"B"|null, "stale": "A"|null, "confidence": 0.0-1.0, "reason": "<at most 25 words: name the asset that can be deleted and what the other asset still holds>"}