akm-cli/docs/migration/release-notes/0.8.0.md

akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cur

Migration notes for akm v0.8.0

This release combines the 0.8.0 CLI/storage break with the final improve-owned
maintenance migration work that landed before release validation closed.

Key operator-facing changes:

- `akm index --enrich` and `akm index --re-enrich` are removed.
- Plain `akm index` now owns metadata enhancement only.
- Memory inference and graph extraction now run from `akm improve` after
  consolidation, not from `akm index`.
- Graph schema redesign (DB_VERSION 12 → 13): `graph_files` re-keyed on
  `entry_id` with FK cascade to `entries(id)`, child tables follow.
  Upgrade drops the graph tables and repopulates them on the next
  `akm improve` cycle; non-graph tables rebuild automatically. Run
  `akm improve` once after the storage migration to repopulate graph data.
- Manual QA and sandbox guidance now require isolating `AKM_DATA_DIR` in
  addition to `HOME`, XDG dirs, and `AKM_STASH_DIR`.
- `akm health` is available for post-upgrade runtime checks against `state.db`,
  task-history integrity, agent availability, and recent improve telemetry.

Primary public command family for 0.8.0:

- `akm improve [<type>|<ref>]`
- `akm propose <type> <name> (--task "..." | --file <path>)`
- `akm proposal list`
- `akm proposal show <id>`
- `akm proposal diff <id>`
- `akm proposal accept <id>`
- `akm proposal reject <id> --reason "..."`

Proposal-queue and improvement workflows are consolidated around this family.
Update scripts, prompts, docs, and agent instructions before upgrading.

Behavior changes worth noting:

- `akm search` with no query now fails with `MISSING_REQUIRED_ARGUMENT`.
- `akm remember --enrich` is fail-soft: if no LLM is configured, the memory is
  still written.
- `akm wiki stash <wiki> <url>` once again fetches and stores URL snapshots in
  `wikis/<name>/raw/`.
- `akm health --since 24h` provides a fast operator check for state-db
  round-trip health, task-log backing, and recent improve outcomes.
- The `akm improve` lock is now properly released even when `openStateDatabase()`
  or budget-timer setup throws, preventing lock leaks (up to 4 hours) on error
  paths.

New in the final 0.8.0 RC cycle:

### End-of-Run Git Sync (`akm improve --sync`)

`akm improve` now auto-commits the git-backed primary stash at the end of every
non-dry-run pass. Detection is based on a `.git` directory — no remote required.

- `default` and `thorough` profiles: sync + push enabled by default
- `quick` and `memory-focus` profiles: sync disabled (lightweight passes)
- `--sync` / `--no-sync`: force on or off for a single run
- `--push` / `--no-push`: push or commit-only override for a single run

The commit message defaults to `akm improve auto-sync` and supports `{token}`
placeholders: `{timestamp}`, `{date}`, `{time}`, `{scope}`, `{refs}`,
`{accepted}`. Configure via `profiles.improve.<name>.sync.message` in config.

The result envelope includes a `sync` field: `{ committed, pushed, skipped,
reason? }`. A `stash_synced` event is emitted to `state.db`. Sync failures are
non-fatal — they never fail a successful improve run.

### Consolidate Reliability

- Pre-flight stale-DB filter: consolidate now filters out entries that have
  become stale in the DB before making any LLM calls, eliminating wasted tokens
  on already-processed content.
- Defense-in-depth merge guards: three layers of guards prevent incorrect merges,
  improving consolidation correctness on edge cases.

### Proposal Drain Refinements

- `DrainDeferReason` now has two variants: `"mid-band"` and `"possible-dup"`.
  The `"possible-contradiction"` variant has been removed.
- `DrainResult` gains a `staged` field: items the judgment tier resolved as
  "accept" that were not yet promoted in queue mode. These are reported as
  resolved, not deferred.
- `contentBodyLineCount` now uses the canonical `parseFrontmatter` for consistent
  CRLF/BOM handling.

### Workflow `when_to_use` Now Optional

Workflow frontmatter no longer requires `when_to_use`. The field is still
supported and recommended but the validator no longer rejects workflows that
omit it.

Release validation status for the final 0.8.0 cut:

- Full repo test suite passed.
- Docker install matrix passed for both Bun and binary install paths.