akm-cli 0.9.31 → 0.10.261002-beta

package/docs/migration/release-notes/0.10.0.md

@@ -0,0 +1,201 @@
+# akm v0.10.0 migration notes
+
+0.10 is a clean-up and tuning release. It covers the daily alphas
+0.10.26101001 through 0.10.26101202 and the monthly releases that follow
+(`0.10.YYMMNN`). It
+removes surface that nothing used, merges CLI spellings, sets the improve
+defaults from measurements, and adds OpenCode 2 support. It adds no `state.db`
+migration and keeps `index.db` at layout 26.
+
+To upgrade from 0.9.15 or later:
+
+```sh
+akm upgrade
+akm migrate status
+akm health
+```
+
+`akm upgrade` installs the new release and runs `akm migrate apply`. Before
+you upgrade, search your scripts, tasks and agent instructions for the removed
+spellings below: they fail with exit 2 and no hint. The full ordered procedure,
+every replacement and the verification steps are in the
+[0.9 to 0.10 migration guide](../v0.9-to-v0.10.md).
+
+## Version floor
+
+0.10 reads what 0.9.15 and later wrote. It converts nothing older. A config in
+the old `stashDir` / `sources[]` / `installed[]` layout, or with an `extraParams`
+key that shadows a first-class engine field, fails to load and names
+`akm migrate apply` under akm 0.9.x. If you are on 0.9.14 or earlier, install
+0.9.31, run `akm migrate apply`, then upgrade.
+
+## Version numbers
+
+A 0.10 release is numbered `0.10.YYMMNN`: the UTC year and month, then the
+release within that month. Every release takes the next number, whatever its
+stage. A prerelease carries its stage only (`-alpha`, `-beta`, `-rc`).
+Prereleases publish to the npm `next` tag and stable releases to `latest`.
+`akm upgrade --next` follows `next`. Versions sort by month and then number, so
+the number says nothing about how big a change is. Read the CHANGELOG, which
+still marks breaking changes. The 0.9 line keeps `0.9.N`.
+
+The daily alphas used an 8-digit patch (`0.10.YYMMDDNN`), which semver sorts
+above every `0.10.YYMMNN`. If you are on one, install the first monthly release
+explicitly once (`npm install -g akm-cli@0.10.261001-beta`); `akm upgrade` will
+not offer it.
+
+## Breaking changes
+
+Each of these is an unknown flag or command (exit 2), with no alias:
+
+- `akm help agents` is gone. Use `akm hints`, or `akm hints --detail brief` for
+  the short guide.
+- `--shape` is gone. `--detail agent` replaces `--shape agent`, and `--detail
+  brief` replaces `--shape summary`. `--detail` takes `brief`, `normal`, `full`
+  or `agent`.
+- `--target` is gone from `import`, `env create`, `env remove`, `secret set`,
+  `proposal accept`, `proposal diff` and `proposal revert`. Use `--bundle`.
+- `akm task validate` is folded into `akm lint --type tasks`. `akm task list`
+  is gone; use `akm search --type task`.
+- `akm config path --all` is gone. `akm info` reports the directories.
+- `akm improve --plan` is gone; use `--dry-run`. `akm improve --auto-accept` is
+  gone; use `akm improve && akm proposal drain --promote --yes`.
+- `--run` and `--since` belong to `akm improve report`. `akm improve report` and
+  `akm improve judge` are real subcommands.
+- `akm workflow create --reset` is gone; use `--force`.
+
+Other breaking changes:
+
+- The built-in improve strategies `quick`, `reflect-distill`, `thorough`,
+  `catchup` and `proactive-maintenance` are removed. Only `default` and
+  `consolidate` are built in. A config block with one of those names still
+  loads, as a user-defined strategy that inherits `default`. A name with no
+  block makes `akm improve` fail and name `default`. The task templates
+  `akm-improve-nightly`, `akm-improve-frequent` and `akm-improve-catchup` are
+  removed; a copy in your bundle keeps its old `--strategy` and must be edited.
+- Improve config keys that measured no effect or that nothing read are removed:
+  `consolidate.antiCollapse`, `p90ChunkSecondsDefault`, `minPoolSize`,
+  `distill.fidelityCheck`, `distill.limit`, `reflect.lowValueFilter`,
+  `memoryInference.cls`, `proactiveMaintenance.limit`, `triage.policy`,
+  `improve.salience.outcomeWeightEnabled` and `salienceThreshold`. A config that
+  sets one still loads; `akm migrate apply` drops it.
+- The GitHub-shaped YAML workflow format is removed, with workflow-step
+  `uses: tasks/...`, `scripts/...` and `commands/...`. Workflows are Markdown
+  only. Top-level `outputs:`, `route` steps and `unit.isolation: worktree` are
+  removed and are lint errors.
+- `BundleAdapter.placeNew()` is removed. Nothing called it.
+- `package.json` has an `exports` map: only `akm-cli/api`, `akm-cli/package.json`
+  and `akm-cli/dist/*` resolve.
+- The runtime conversions for config older than 0.9.15 are removed, as above.
+
+## New
+
+- **OpenCode 2.** akm detects the OpenCode major from the engine's binary and
+  drives OpenCode 1 or 2 through its own adapter, for SDK dispatch, CLI
+  dispatch, session history and config import. OpenCode 1 keeps working and
+  logs one warning recommending OpenCode 2. `akm upgrade` and `akm health` know
+  the new `akm-opencode-v2` plugin.
+- **`akm-cli/api`.** `curate(query, options)` returns exactly what
+  `akm --detail agent -q curate` prints, computed in-process. It is for the
+  plugins; nothing else is a public API.
+- **Feedback changes ranking.** `akm search` and `akm curate` scale each hit by
+  your feedback on it. The effect is small and the same for every asset: about
+  +2, +3, +5 and +9 percent for 1, 2, 5 and 20 positives. Improve, task and
+  audit feedback does not count.
+- **Distill extends a lesson** that a memory repeats, as a proposal for a person
+  (`distill-update`).
+- **Child workflows** keep a simple form: `unit: { workflow: workflows/<name>,
+  with: {...} }`. A param's `default:` is now applied at run start.
+- **`akm proposal extract`** is Evolving, not Experimental.
+- **`akm improve <scope>`** warns when the scope matches no asset.
+- **Daily-build versioning** and the `next` channel, above.
+
+## Changed defaults
+
+- The `default` improve strategy now drains the proposal queue in `promote`
+  mode with judgment off, up to 200 accepts a run. It accepts what a quality
+  judge already passed and the retirements the consolidate pair pass staged.
+  The judgment tier is off in every built-in strategy and may accept only
+  consolidate promotions. Set `improve.strategies.default.processes.triage.enabled`
+  to `false` to leave every proposal for review.
+- The proactive-maintenance lane is on in `default`: up to 15 assets a run that
+  have no fresh feedback and are 30 days past their last reflect or distill. Its
+  proposals always wait for a person.
+- A manual fix (`akm feedback --replace/--with/--source`, `--superseded-by`,
+  `--outdated`) applies at once instead of queuing a proposal. `akm proposal
+  revert` undoes it.
+- `akm improve` syncs a git-backed bundle before it plans, as `akm sync` does,
+  and again at the end. A conflict warns and the run continues. `--no-sync` and
+  `--no-push` apply to both.
+- A reflect revision the judge does not pass but scores 3.5 or more goes to a
+  person as `judge-uncertain` instead of locking the asset for 14 days. A
+  missing distill judge queues for review instead of a 30-day lock.
+- `captureMode: hot` memories are consolidated like any other memory.
+- Retire proposals expire by age (`archiveRetentionDays`, default 90) like every
+  other proposal. The per-run `improve` and `index` log files are purged under
+  `improve.eventRetentionDays`.
+- A standalone `akm proposal drain` resolves to promote mode on a stock install
+  and asks for confirmation.
+
+## Removed
+
+- Reflect's retrieval regression gate. It refused 12 to 17 percent of the
+  revisions the judge had passed and lowered the defects fixed. A judge-passed
+  revision is now minted as a proposal with no further check. It had no config
+  key.
+- The high-salience improve lane.
+- The hint tables and error messages for the 0.9.0 renames, the `vault:`, `env:`
+  and `secret:` ref rejections, the `--from stash|both` error, and the bespoke
+  errors for retired config keys. They are ordinary unknown commands, flags or
+  keys now.
+- The `targetVocab` marker on `task_history` rows and the `"mcp"` package
+  keyword.
+
+## Plugins
+
+- `akm-opencode` is for OpenCode 1. `akm-opencode-v2` is for OpenCode 2. Each
+  pins one exact `akm-cli`, and `akm upgrade` holds the CLI to the pin.
+- OpenCode caches the plugin spec it resolved and does not re-check it. A new
+  build is picked up only after the plugin's cache folder is cleared. `akm
+  upgrade` does this for `@latest` (or `@next`) when no OpenCode process runs.
+  A spec pinned in your OpenCode config is left alone.
+- OpenCode 1 asks before reading or writing outside the project directory.
+  OpenCode 2 does not unless its config says `ask`, so akm's rejection of a
+  permission request only happens there once you add the rule. akm changes no
+  OpenCode default. See [Configuration](../../reference/configuration.md#engines).
+- Plugins and scripts that pass `--shape agent` must move to `--detail agent` in
+  step with the CLI. A call with `--shape agent` fails on 0.10, and one with
+  `--detail agent` fails on 0.9.
+
+## Fixes worth naming
+
+- `akm sync` fetches and merges what another host pushed before it pushes. It
+  used to exit 70 once another host had pushed.
+- The 02:00 nightly `akm improve` no longer loses its night to the consolidate
+  task's lock. The shipped consolidate task passes `--timeout-ms 3600000`.
+- Command tasks (`uses: commands/...`) get the 6-hour unattended default
+  timeout.
+- A transient reflect failure no longer uses up the feedback that planned it.
+- A run killed by its budget watchdog leaves a record and commits what it wrote.
+- The extract per-session lock is reclaimed only from a dead holder.
+- Memory inference writes to the default bundle and no longer reverts an edit
+  made to the parent memory during the model call.
+- The consolidate pair judge no longer treats a later date alone as a
+  replacement: a note replaces another only when both are about the same named
+  thing. On the eval, `gpt-oss:120b` unsafe retirements went from 1, 2, 1 to
+  0, 0, 0 over three runs.
+- A gateway that answers 5xx `format_ignored` no longer fails every schema call,
+  and a call recovered by the retry counts as one successful call in the usage
+  rows.
+- `akm proposal revert` of a retirement works after the 30-day archive purge.
+- `akm search` no longer warns "no embedding provider is configured" on a default
+  install.
+- A signal to `akm agent` now ends the CLI harness it started. An OpenCode 2 SDK
+  dispatch ends at once when akm rejects a permission request, instead of waiting
+  out its deadline.
+
+For the rules each improve process follows in 0.10, see
+[the 0.10 process rules](../../architecture/0.10-process-rules.md). For the
+entry behind each item, run `akm help migrate <build number>` (for example
+`akm help migrate 0.10.26101201`) or read the
+[CHANGELOG](https://github.com/itlackey/akm/blob/main/CHANGELOG.md).

package/docs/migration/release-notes/README.md

@@ -7,6 +7,7 @@ live one level up in `docs/migration/`.
 
 ## Available notes
 
+- [0.10.0](0.10.0.md) — The 0.10 series: 0.9.15 version floor, merged CLI spellings, `default`/`consolidate` strategies only, OpenCode 2, feedback-scaled ranking, and `0.10.YYMMNN` versions.
 - [0.9.19](0.9.19.md) — Bundle-scoped improve planning, proposal reopen, and consolidate/distill guardrails.
 - [0.9.17](0.9.17.md) — Retire proposals, declared links replacing the LLM entity graph, and scoped improve planning.
 - [0.9.16](0.9.16.md) — Source-bound scheduler grants, local execution authority, and split unsafe overrides.