akm-cli 0.9.31 → 0.10.26101001-alpha

package/CHANGELOG.md

@@ -6,6 +6,245 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.26101001] - 2026-10-10
+
+### Added
+
+- **OpenCode 2 is the primary OpenCode integration; OpenCode 1 keeps working (#1049).** akm detects the major from
+  the engine's binary (`<bin> --version`, once per binary per process; `opencode2` is preferred when it is on PATH)
+  and drives it through a per-major adapter for SDK dispatch (`opencode-sdk`, on `@opencode/client` 2.0.26 or
+  `@opencode-ai/sdk` 1.2.20), CLI dispatch (`opencode run`, which adds `--standalone` on OpenCode 2 so no background
+  service is left running), session history (chosen from `opencode.db`'s own tables, read-only, with retained
+  OpenCode 1 rows still readable after a native upgrade) and native config import. OpenCode 1 warns once that
+  upgrading is recommended; a binary of an unknown major is driven as OpenCode 2 with a warning, never refused.
+  `akm upgrade` and `akm health` know the `akm-opencode-v2` plugin beside `akm-opencode`.
+- **`akm-cli/api`: the one supported programmatic entry point.** `curate(query, { limit, type, format })` returns
+  exactly the stdout of `akm --detail agent -q curate …`, computed in-process, and rejects with the CLI's message and
+  `code`. It is for in-process recall by the akm plugins; everything else stays CLI-only. `package.json` gains an
+  `exports` map (`./api`, `./package.json`, `./dist/*`); `bin` and `files` behave as before. See
+  [`docs/reference/api.md`](docs/reference/api.md).
+- **Distill extends an existing lesson that a memory repeats (#1090).** When the writer's lesson repeats one the library
+  holds (the judge scores its non-redundancy 2 or below), or the writer answers `NONE` with a lesson nearby, distill
+  asks for that lesson's body again with the lines the memory adds. If every existing line is kept, and the judge
+  passes the added lines against the lesson and the memory, the update is a pending proposal on the lesson's own
+  ref (reason `distill-update`, with the lesson's before-hash), left for a person: the triage drain does not accept
+  it. Otherwise nothing is proposed and the outcome is what it was. The result and the `distill_invoked` event carry
+  `updatesExisting: true`. No new setting; it needs the quality gate.
+
+### Removed
+
+- **The GitHub-shaped YAML workflow format (#1096).** A `.yml` workflow (`name`/`on`/`jobs`, one job, `uses:` and `run:`
+  steps) is gone, with everything that existed only to carry it: workflow-step `uses: tasks/<ref>` (task composition),
+  `uses: scripts/<ref>` and `uses: commands/<ref>` targets, the `with:` rejection classifier for them, YAML `on.schedule`
+  triggers (and the scheduler sync of them), and the `script` frozen target. `.yml` under `workflows/` is skipped at
+  index time with a message saying it must use `.md`. Nothing in the owner's bundle or in OpenPalm used it. **Kept:** a
+  task that runs a workflow (`uses: workflows/<ref>`, or a `run:` calling `akm workflow run`) is a task feature and is
+  unchanged. A stored run whose plan has a `script` target can no longer be decoded and is abandoned like any other
+  undecodable plan.
+- **Top-level workflow `outputs:` (#1096).** Its only consumer was a parent reading a child's exports. A completed
+  child workflow now returns the output of its last step, so `outputs:` is a lint error and the child-output reference
+  check at freeze is gone; a parent reads `steps.<composing-step>.output`. The `outputs_json` column stays readable.
+- **Workflow `route` steps (#1096).** A step can no longer declare `route:` (branch on a value to a later step). It was
+  unused by any workflow found, and its cost was the replay journal for route decisions and cascaded skips. Branching is
+  an `exec` step or an agent step that reads its inputs, plus a gate for "go back and fix it". `route` is now an
+  unknown-key lint error; a stored plan that still has a route step cannot be decoded, so that run is abandoned.
+- **`unit.isolation: worktree` (#1096).** A workflow unit can no longer declare per-attempt git-worktree isolation
+  (`exec/worktree.ts` and the attempt prepare/cleanup in the native executor). It was unused by any workflow found, and
+  the largest standalone block in the engine. `unit.isolation` is now an unknown-key lint error; a stored plan that
+  still carries it decodes and runs the unit in the engine's working directory. The `worktree_path` columns stay readable.
+- **Runtime conversion of config older than 0.9.15 (#1091).** 0.10 reads what 0.9.15 and later wrote; an install on an
+  earlier release runs `akm migrate apply` under akm 0.9.x first. Removed: the in-memory `stashDir`/`sources[]`/
+  `installed[]` to `bundles` conversion (`legacy-source-shape-shim.ts`), the `engines.*.extraParams` lift onto
+  `temperature`/`maxTokens`/`enableThinking`/`reasoningEffort`, and the `{kind, ref, sourceId}` write-back of
+  `scheduler.enabled` that kept 0.9.16 able to read what a newer release wrote (0.10 writes plain refs, still reads the
+  object form). A config with a retired source key now fails to load with one message naming `akm migrate apply` under
+  akm 0.9.x; a legacy `extraParams` key is refused with the first-class field to set. Kept, because 0.9.15 or 0.9.16
+  wrote them: scheduler adoption for a config with no `scheduler.enabled`, the `{kind, ref, sourceId}` reader, and the
+  irVersion 5 frozen-plan reader (there was no separate irVersion 4 reader to remove). `akm migrate apply` and
+  `akm migrate status` are unchanged for 0.9.15 and later data; the task-source migrator moved to
+  `scripts/akm-migrate/migrate/`. See `STABILITY.md` and `docs/architecture/persisted-data-compat.md`.
+- **The `quick`, `reflect-distill`, `thorough` and `catchup` built-in improve strategies, and the `akm-improve-frequent`
+  and `akm-improve-catchup` task templates (#1130).** Measured (nightly eval, n=3, `gpt-5.6-terra` and `qwen3.8-27b`):
+  `quick` solved 0.76 / 0.75 items against `default`'s 0.92 / 0.89, `reflect-distill` 0.78 / 0.77, and `thorough` (the
+  judged triage drain) 0.67 / 0.70 with harmed items at 9 / 6.3 (unsafe retirements accepted, an exact fix applied
+  unreviewed); `catchup` was identical to `consolidate` on the pool (it differed only in the judged triage drain, `maxChunkSize` 50 instead of 25, and `minPoolSize: 0`, which is already the default). An `improve.strategies.<name>` block with one of
+  these names stays valid as an ordinary user-defined strategy, but it now inherits `default` and no longer carries the
+  old built-in's settings (for example the triage drain). `--strategy` or `defaults.improveStrategy` naming one with no
+  such block fails at resolution with an error that names `default`; config load still succeeds. The shipped
+  `akm-improve-nightly` task would now run `default` at 02:15, the same as the `core/improve` task at 02:00, and the
+  hourly `akm-improve-frequent` task would only repeat that pass; `akm-improve-catchup` ran the same `consolidate` as
+  `akm-improve-consolidate`. All three are gone, and setup's server-install preselection now suggests `core/improve`. A task copied from
+  any of them into a bundle keeps its `--strategy` and must be changed to `default` or `consolidate`. (#1130)
+- **The high-salience improve lane and `improve.salience.salienceThreshold` (#1129).** The lane admitted nothing in
+  the measurement and was reachable only by back-dating feedback. The key still loads from an old config with a
+  warning and does nothing; `akm migrate apply` drops it. The `high-salience` lane name stays valid on rows older releases wrote.
+- **The `proactive-maintenance` built-in improve strategy (#1129).** The lane now lives in `default`. A
+  `improve.strategies.proactive-maintenance` block in your config keeps working as a user-defined strategy, merged
+  onto `default`; `defaults.improveStrategy: "proactive-maintenance"` without such a block still loads and fails
+  when improve runs, with the same "removed in 0.10" error as `quick` and the other removed strategies (#1130).
+- **`BundleAdapter.placeNew()` (internal, #1091).** The optional adapter method, its nine implementations and their
+  tests were never called: every write already resolves through the fixed type-to-directory table. No behaviour
+  change. Writable bundles in a layout other than akm's own would need it back; see #1163.
+
+### Changed
+
+- **Child workflows are kept in a simple form (#1096).** A markdown step declares `unit: { workflow: workflows/<name>,
+  with: { <param>: <literal or { from: <reference> }> } }` and the engine starts the child as its own run and drives it
+  to completion; the child's last step output is the composing step's output. The form is Experimental. The freeze,
+  idempotent publish, resume, blocked-child recovery, cycle check and `workflow list --children` behaviour of the existing
+  child executor is unchanged.
+- **`default` drains the proposal queue through the deterministic gates (#1143).** The `default` strategy now runs
+  triage in `promote` mode with judgment off, up to `maxAcceptsPerRun: 25` accepts per run, so the backlog drains
+  without `experimental.improveAutonomy`. The nightly eval's baseline is exactly this path (`proposal drain --promote`
+  without judgment): 0.91 (terra) and 0.89 (qwen) of items solved, 0 to 1 harmed; the judged drain is what caused
+  harm (#1132). The autonomy gate's `triagePromote` lane is now gated only when the triage stage has judgment on: a
+  promote with judgment on and no opt-in is still downgraded to `queue` and reported (`improve_skipped`,
+  `akm task doctor`). Memory inference and memory cleanup stay gated. No new setting. (#1143)
+- **`akm improve` plans the proactive-maintenance lane's picks again, and the lane is on in `default` (#1129).**
+  Measured on assets with silent defects and no feedback (8 planted): 0 fixed with the picks scored only, 6 to 7 with
+  them planned, no harm, about five times the model calls. The picks carry the `proactive` lane on their
+  proposals. The cap against a proposal flood already existed and is now consistent: `maxPerRun` limits the picks per
+  run, `dueDays` (30) admits only an asset not reflected or distilled for 30 days, and reflect's `limit` (25) bounds
+  the run. The code fallback for `maxPerRun` is 15, the shipped value, where it was 25. No new setting.
+  `--require-feedback-signal` turns the lane off for a run.
+- **The judged drain accepts only consolidate promotions, and no built-in strategy turns judgment on (#1132).** On the
+  nightly eval, judging every proposal kind with `experimental.improveAutonomy` solved about half the items
+  (0.49 gpt-5.6-terra, 0.53 qwen3.8-27b) and harmed 14 and 11, changing 18 and 21 notes outside the planted set: it
+  accepted unsafe retirements and applied exact fixes unreviewed. Judging promotions alone was reasonable. The judgment
+  tier now accepts only a consolidate promotion; any other kind it would accept (a retirement, an exact fix, a reflect
+  revision) is left for a person with reason `judgment-not-promotion`, whatever the strategy says. `thorough`, `catchup`,
+  `reflect-distill` and `proactive-maintenance` no longer enable triage judgment. Deterministic promote gates are
+  unchanged. (#1132)
+- **Built-in improve strategies are patches onto `default`, not "complete presets" (#1130).** `docs/reference/configuration.md`
+  said otherwise; the strategy list in the docs, the `--strategy` help and the hints now name only `default`
+  and `consolidate`. (#1130)
+- **A proposal from the proactive lane waits for a person (#1147).** With the lane on in `default` and the default
+  drain promoting through the deterministic gates, a reflect edit on an asset with no feedback was accepted unattended
+  once reflect's judge passed it (the nightly eval showed `when_to_use`, `type` and provenance stamps and a title
+  heading added to assets no one had asked about). `proposal drain` now never accepts a proposal whose
+  `eligibilitySource` is `proactive`, through a deterministic gate, the judgment tier or an earlier staged accept: it is
+  left for review with reason `proactive-needs-review` (and is not sent to the judgment tier). Feedback-driven
+  proposals (`signal-delta`, `scope`) are unchanged. No new setting. (#1147)
+- **0.10 releases are daily builds, `0.10.YYMMDDNN`, with `-alpha`, `-beta` and `-rc` stages (#1089).** The patch
+  number is the UTC year, month and day plus the build that day (`NN`, `01` to `99`), two digits each: the first build
+  on 2026-10-10 is `0.10.26101001`. A prerelease carries its stage only (`0.10.26101001-alpha`, no `.N`), so one build
+  is promoted `-alpha` < `-beta` < `-rc` < `0.10.26101001`; prereleases publish to the npm `next` tag and stable builds
+  to `latest`. The Release workflow validates the format and takes a new `stage` input (`scripts/release-version.ts`);
+  `bun scripts/release-version.ts next` prints the next free build number for today from the versions on npm. Versions
+  sort by date across months and years, so `akm upgrade` and semver ranges order them correctly. The 0.9 line keeps
+  `0.9.N`. See `STABILITY.md`. (#1089)
+
+### Removed
+
+- **Six improve knobs that measured no effect (#1131).** Each is removed with the code that served only it; a config
+  that still sets one loads (named once by the unknown-key warning, dropped by `akm migrate apply`).
+  - `processes.consolidate.antiCollapse`: the random cluster-member injection. Identical results with it off on an
+    80-memory pool.
+  - `processes.consolidate.p90ChunkSecondsDefault`: the up-front budget cap on the consolidation pool keeps its
+    behaviour with a fixed 30 s per chunk. Identical at 10, 30 and 90 s under a 180 s budget.
+  - `processes.consolidate.minPoolSize`: the minimum-pool skip, its `pool_below_min_size` `improve_skipped` reason and
+    the `minPoolSize` / `gates.minimumPool` fields of the consolidation plan. It was bypassed by `--strategy`, and the
+    documented default (500) differed from the code's (0). `improve_runs` rows that carry the plan fields still read.
+  - `processes.distill.fidelityCheck`: the negation-pattern contradiction check. No difference at n=3.
+  - `processes.reflect.lowValueFilter`: the low-value tier of the reflect noise classifier. Reflect edits only
+    frontmatter, which the filter always passes. No-op and cosmetic edits are still refused.
+  - `improve.salience.outcomeWeightEnabled`: the toggle and its parity weights. The outcome term stays on
+    (w_e 0.25, w_o 0.15, w_r 0.60), as it was by default.
+
+- **`akm workflow create --reset` (#1091).** Declared since 0.9.12 as a deprecated alias of `--force`, never read.
+  `--force` alone replaces a workflow with a fresh template; `--force --from <file>` replaces it from the file.
+- **`akm improve --plan` (#1091).** An exact alias of `--dry-run` with no other callers. Use `--dry-run`; it prints the
+  same `plan.processes` routing table.
+- **`akm task list` (#1091).** A delegating alias of `akm search --type task` (added in 0.9.15, #951) with no callers
+  in the plugins, akm-eval or OpenPalm. Use `akm search --type task`.
+- **Improve config keys nothing read (#1091).** `processes.distill.limit`, `processes.memoryInference.cls`,
+  `processes.proactiveMaintenance.limit` (an alias of `maxPerRun`) and `triage.policy` (set in the shipped `default`
+  strategy, read by no code) are gone from the schema and the shipped strategy. A config that still sets one loads
+  (named once by the unknown-key warning). `plan.triage.maxDiffLines` leaves the plan type; stored runs that carry it,
+  or `plan.proactive.configured.limit`, still decode. `processes.distill.cls` is read and stays. OpenPalm's improve
+  editor writes the strategy-level `limit`, not per-process ones, so the process `limit` of reflect and consolidate
+  stays.
+- **The `targetVocab: 2` marker on `task_history` rows, and the `"mcp"` package keyword (#1091).** Nothing read the
+  marker since migration 025 backfilled the old result vocabulary, so new rows no longer carry it and a stored one is
+  ignored; its newer-than-2 warning is gone. akm has no MCP code left, so `package.json` no longer lists `mcp`.
+- **The hard-error and bespoke-warning hints for old config keys (#1091).** `defaults.llm`, `defaults.agent` and
+  `defaults.improve` (rejected since 0.9), the `feedbackDistillation` process (rejected since 0.8.0), and the engine
+  settings under `index.<pass>` and `index.stalenessDetection` (dropped with a bespoke message) now load like any other
+  unknown key: named once by the unknown-key warning, ignored, and dropped by `akm migrate apply`.
+- **`akm improve --auto-accept` is a hard error (#1091).** It was removed in 0.9.0 and has been accepted-and-warned
+  since; it is now an unknown flag like any other (exit 2), and `--auto-accept 90` no longer reaches the scope. Use
+  `akm improve && akm proposal drain --promote --yes`, or a `triage` block with `applyMode: "promote"`.
+- **The hint tables for the 0.9.0 renames (#1091).** `RETIRED_COMMAND_HINTS` (39 entries), `RETIRED_FLAG_HINTS` (5) and
+  `SELF_DIAGNOSED_FLAGS` (`src/cli/retired-commands.ts` is gone), the per-command `--target`, `--source`, `--scope`,
+  `--enrich`/`--re-enrich` and `proposal drain --profile` rejections, the `akm improve canary` scope rejection, the
+  `akm show` colon-ref tip and the `<type>:` search tip. A retired command is now an ordinary `UNKNOWN_COMMAND` (with a
+  did-you-mean when one is close, within a third of the name's length) and a retired flag an ordinary `UNKNOWN_FLAG`
+  (exit 2), with no migration pointer. The same goes for the `--from stash|both` rename error (a bundle may now be named
+  `stash`), the `vault:`/`env:`/`secret:` ref rejections (`env/`, `secrets/`, `secret://` and `${secret:NAME}` are
+  unchanged), the `config get` replacement hints for `stashDir`, `sources`, `installed`, `wiki`, `wikiName` and `llm`,
+  and the retired-spelling notes in the agent hints.
+  `task run`/`task explain` no longer reserve the input name `target`, so a task may declare an input of that name.
+  `akm improve canary` is now an asset-type scope that matches nothing.
+- **`akm help agents` (#1091).** It printed the same two guides as `akm hints` with the opposite default (short, with
+  `--full` for the complete one). `akm hints` is the one command: the complete guide by default, `--detail brief` for the
+  short one (`akm help agents >> AGENTS.md` becomes `akm hints --detail brief >> AGENTS.md`). `akm help agents` is now an
+  ordinary unknown command.
+- **`--shape` (#1091).** It acted on three commands (`search`, `curate`, `show`; `summary` only on `show`) while about 55
+  others ignored it and `--detail`. `--detail agent` replaces `--shape agent`, and `--detail` now takes
+  `brief|normal|full|agent`. `--shape summary` had no caller; use `--detail brief` on `show`. `--shape` is an unknown flag
+  (exit 2, `UNKNOWN_FLAG`) with no alias, so callers must change in step: the akm plugins, akm-eval's retrieval,
+  skillret and longmemeval benchmarks, and `akm help agents`-style scripts. `INVALID_SHAPE_VALUE` is gone, and
+  `INVALID_DETAIL_VALUE` now lists `agent`. The CLI reference no longer claims `--shape summary` errors outside `show`
+  (it warned and fell back to `agent`).
+- **`--target` on `import`, `env create`, `env remove`, `secret set` and `proposal accept`/`diff`/`revert` (#1091).**
+  `--bundle` is the one write-destination flag, as on `remember`, `clone`, `improve` and `task`; `--target` is an
+  unknown flag (exit 2) with no alias. The plugins, akm-eval and OpenPalm pass no `--target`. Errors and hints that said
+  `--target` now say `--bundle`.
+- **`akm task validate` (#1091).** Folded into `akm lint --type tasks`, as `akm workflow validate` was. Lint already parsed
+  every task file through the same version router; it now also runs the two gates `akm task sync` runs before it installs
+  a schedule (the cron suits the local scheduler backend; each schedule entry's `inputs` satisfy the declared contract),
+  so it never reports clean a task sync would refuse. Gone with the command: the `valid`/`blocked`/`invalid`/`not-a-task`
+  outcome, the `resolved` shape and the bare-path argument (point `akm lint --dir` at a bundle root). The
+  owner's crontab and tasks, the plugins, akm-eval and OpenPalm do not call it.
+- **`akm config path --all` (#1091).** `akm info` already reports the bundle, config, data, cache and state directories
+  (the index is `<dataDir>/index.db`), and `--all` was the one place `config path` printed an envelope instead of a bare
+  path. `akm config path` still prints the config file path and still runs when the config itself fails to load; `--all`
+  is an unknown flag (exit 2). Hints that sent you to `config path --all` now say `akm info`.
+- **`akm improve report` and `akm improve judge` are real subcommands (#1091).** They were magic values of the `scope`
+  positional. Both spellings keep working. `--run` and `--since` are now flags of `report` alone, so `akm improve --run x`
+  and `akm improve skills --since 7d` are unknown flags (exit 2) instead of a usage error from a hand-written check;
+  `--strategy` is `judge`'s own flag too. `akm improve [scope]` is unchanged, and `akm-eval`'s judge-gate keeps calling
+  `akm improve judge`.
+
+### Fixed
+
+- **A workflow param's `default:` is now applied (#1096).** An omitted param was absent from the run and the unit
+  prompt said `Run parameters: {}`, so workflows restated their defaults in prose. A run now starts with each declared
+  default for the params it was not given; explicit values still win.
+- **A call recovered by the retry without the schema is one successful call in the usage rows.** The failed schema
+  attempt (`format_ignored` or a 4xx schema rejection) was recorded as a failed call with 0 tokens next to the retry's
+  success, so `akm improve` usage showed e.g. `distill freellm/gpt-oss:120b calls 1 failures 1` beside 17 successes. Only
+  the retry is recorded now; a retry that also fails is still one failure.
+- **Distill's lesson update (#1139) is judged as the lesson it makes, and costs a call only for a lesson that is named.**
+  The judge read only the added lines as a standalone lesson, so a single added fact failed `reusable` and no update
+  passed (0 of 8 on the akm-eval `lesson-update` class, on two models). It now reads the extended lesson (old body plus
+  added lines) as one lesson, in the same single call: reusable and grounded as a whole (a line is grounded when the
+  memory or the lesson states it), and each added line must state something the lesson does not already hold. An update is also tried only for a related lesson that the writer's NONE reason, or the judge's
+  non-redundancy finding, names, or for the only related lesson, not for every lesson among the nearest three. The
+  update writer lists the memory's new facts before the body, and an update that lists none is not proposed. (#1090)
+- **consolidate's pair judge no longer lets a later date alone make one note replace another (#1134).** After the
+  same-age fix (#1146), `gpt-oss:120b` retired notes about a different named thing (two partners on one template:
+  "B is newer and replaces Alder with Birch") as `supersedes`, 1 to 2 unsafe retirements of 60 per run where the build
+  before it had none. The pair prompt now says a note replaces another only when both are about the same named thing
+  (service, integration, partner, component, region, file), and that notes about different named things never replace
+  each other whatever their dates; `unrelated` covers different named things written to one layout. Measured with
+  akm-eval `evals/consolidate`, per-case n=3: `gpt-oss:120b` unsafe retirements 1, 2, 1 -> 0, 0, 0 with recall
+  0.97 -> 0.99; qwen3.8-27b stays at 0 unsafe, recall 0.70.
+- **A gateway that answers 5xx `format_ignored` no longer fails every schema call (#1150).** A `provider_error` 5xx whose
+  body names the response format (`format_ignored`, `response_format` or `json_schema`) is now answered like the 4xx
+  schema rejection: one retry without the schema, remembered for the connection. `gpt-oss:120b` through the lab
+  gateway needed `supportsJsonSchema: false` set by hand. Other 5xx answers keep the transient-retry path. (#1150)
+
 ## [0.9.31] - 2026-10-09
 
 A patch release: concurrent config writes no longer lose a change, OpenAI's reasoning models work as `llm`
@@ -13,6 +252,16 @@ engines, `akm improve --require-engines` probes send API keys, and the npm packa
 
 ### Fixed
 
+- **consolidate's pair judge no longer reads two same-age notes with different values as an update (#1134).** On the
+  60 labelled pairs `gpt-5.6-terra` retired 10 notes that held a claim the kept note lacked, in every run, always
+  from the ten `contradicts` pairs: it labelled them `supersedes`, because the prompt called B "newer" although both
+  notes had the same file time, and listed no claim for the old value because "updates" were left out of the lists.
+  The judge now sees "A (same age as B)" / "B (same age as A)" when the dates tie, and a different value counts as a
+  replacement only when B says so or is created later; otherwise both values are listed and the pair is
+  `contradicts`. Measured with akm-eval `evals/consolidate`, n=3 per-case: terra unsafe retirements 10 of 60 ->
+  1 to 3 (first prompt) and 0 on the final build's first run; qwen3.8-27b stays at 0 unsafe, recall 0.69 -> 0.71.
+  Pool (80 memories): terra 2 unsafe per run -> 0 to 2; qwen 0, recall 0.77 -> 0.79.
+
 - **`akm improve --require-engines` sends each engine's API key with its probe.** The probe used the engine's
   connection as resolved, where the key is still a symbolic reference that a dispatch reads only when it sends a
   request, so every keyed endpoint (OpenAI, a gateway that enforces auth) answered 401 and the run stopped with
@@ -56,6 +305,10 @@ plugin on a host that follows `akm-opencode@next`.
 
 - **`akm upgrade` is Stable**, including its plugin step and `--next`, after real-host, empty-container and
   failure-path runs on 0.9.28 (#1099).
+- **`akm proposal extract` and the improve `extract` process move from Experimental to Evolving.** The extract eval
+  (akm-eval `evals/extract`, n=3) measured insights saved 1.00 (terra) / 0.97 (qwen), routine sessions left empty
+  1.00, and planted instructions saved 0. Evolving rather than Stable because 0.10 is still settling the improve
+  defaults; the eval stays its gate (#1133).
 
 ### Fixed
 

package/STABILITY.md

@@ -12,6 +12,40 @@ out in the CHANGELOG with a migration note. The 0.10.x series returns to bug
 fixes and tuning, and aims to restore the normal discipline of breaking
 changes only in major and minor releases.
 
+**Version floor (0.10, #1091).** 0.10 reads what 0.9.15 and later wrote: config,
+`state.db`, task sources, frozen workflow plans and scheduler rows. It does not
+convert anything older. An install on an earlier release runs `akm migrate
+apply` under akm 0.9.x first, then upgrades; a 0.10 reader that meets an older
+shape refuses with one message saying so. See
+[`docs/architecture/persisted-data-compat.md`](docs/architecture/persisted-data-compat.md).
+
+**CLI spellings merged in 0.10 (#1091).** Each of these is an unknown flag or
+command (exit 2) from 0.10, with no alias and no deprecation period; the new
+spelling is in the CHANGELOG entry and the CLI reference.
+
+| Gone | Use |
+| --- | --- |
+| `akm help agents` | `akm hints` (`--detail brief` for the short guide) |
+| `--shape agent` | `--detail agent` |
+| `--shape summary` | `--detail brief` (it only had a projection on `akm show`) |
+| `--target` on `import`, `env create`, `env remove`, `secret set`, `proposal accept`, `proposal diff`, `proposal revert` | `--bundle` |
+| `akm task validate <path>` | `akm lint --type tasks` |
+| `akm config path --all` | `akm info` |
+| `--run` / `--since` on `akm improve` | `akm improve report --run` / `--since` |
+
+**Version numbers (0.10 onward, #1089).** A 0.10 release is a daily build,
+`0.10.YYMMDDNN`: `YY` the UTC year, `MM` the month, `DD` the day and `NN` the
+build that day (`01` to `99`), each two digits. The first build on 2026-10-10 is
+`0.10.26101001`, the second `0.10.26101002`. A prerelease carries its stage
+only: `0.10.26101001-alpha`, `-beta` or `-rc`, with no `.N`. One build is
+promoted by publishing the same `YYMMDDNN` with the next stage and then without
+one (`-alpha` < `-beta` < `-rc` < the build). Prereleases publish to the npm
+`next` tag and stable builds to `latest`; `akm upgrade --next` follows `next`.
+Versions sort by date, so semver ranges and `akm upgrade` order them correctly
+across months and years. The patch number no longer says how big a change is:
+read the CHANGELOG, which still marks breaking changes. The 0.9 line keeps
+`0.9.N`, and `0.11` restarts on the same daily scheme.
+
 This document classifies **every** user-facing surface by stability so you can
 decide which parts of `akm` are safe to script against today and which to
 treat as still-evolving. If a surface is not listed here, that is a bug —
@@ -87,6 +121,8 @@ enumeration of the whole `proposal` noun group.
 | `akm models` | Evolving | `list` and `copy-defaults` for model intent aliases. |
 | `akm lint` | Evolving | |
 | `akm improve` | Evolving | Review-first by default; mutating lanes require `experimental.improveAutonomy` — see below. |
+| `akm improve report` | Evolving | Subcommand since 0.10 (was a magic `scope` value); owns `--run` and `--since`. |
+| `akm improve judge` | Evolving | Subcommand since 0.10 (was a magic `scope` value); reads one revision as JSON on stdin and writes nothing. |
 | `akm proposal list` | Stable | See reconciliation note above. |
 | `akm proposal show` | Evolving | |
 | `akm proposal diff` | Evolving | |
@@ -95,10 +131,9 @@ enumeration of the whole `proposal` noun group.
 | `akm proposal reopen` | Evolving | New in 0.9.19; undoes a rejection. |
 | `akm proposal revert` | Evolving | |
 | `akm proposal drain` | Evolving | |
-| `akm proposal extract` | Experimental | Former top-level `akm extract`. Session extraction quality is still being measured (0.10, #1094). |
+| `akm proposal extract` | Evolving | Former top-level `akm extract`. Promoted from Experimental in 0.10 (#1133): the extract eval measures it. Evolving, not Stable, because 0.10 is still settling the improve defaults. |
 | `akm proposal new` | Evolving | Former top-level `akm propose`. |
 | `akm help` | Stable | |
-| `akm help agents` | Stable | |
 | `akm help migrate` | Stable | Only renders release notes. |
 | `akm hints` | Stable | Format-exempt agent guide; `--detail brief` selects the compact version. |
 | `akm completions` | Stable | Format-exempt (emits shell script source). |
@@ -117,8 +152,6 @@ enumeration of the whole `proposal` noun group.
 | `akm task sync` | Evolving | |
 | `akm task doctor` | Evolving | |
 | `akm task explain` | Evolving | New in 0.9.2; secret-shaped values in provenance output are redacted on a best-effort heuristic basis (not a guarantee). |
-| `akm task validate` | Evolving | New in 0.9.11; read-only, and the only `task` subcommand that takes a bare filesystem path instead of a ref — the file need not belong to any configured bundle. |
-| `akm task list` | Evolving | New in 0.9.15 (#951); a pure delegating alias for `akm search --type task` — same envelope, no separate implementation. |
 
 ## Stable
 
@@ -157,7 +190,7 @@ enumeration of the whole `proposal` noun group.
 - **Read commands** — `akm search`, `akm show`, `akm bundle list`, `akm curate`,
   `akm info`, `akm config get`, `akm config list`, `akm config path`,
   `akm env list`, `akm secret list`, `akm proposal list` (list filters),
-  `akm help`, `akm help agents`, `akm hints`, `akm completions`.
+  `akm help`, `akm hints`, `akm completions`.
 - **Write commands core surface** — `akm bundle add`, `akm bundle update`,
   `akm bundle remove`, `akm clone`, `akm import`, `akm sync`, `akm index`,
   `akm bundle create`, `akm setup`, `akm remember`, `akm feedback`,
@@ -195,12 +228,11 @@ enumeration of the whole `proposal` noun group.
   fetch**: a registered renderer fires on the shape of the result (`akm health
   --report` carries the report dataset in the envelope, so the same data is
   available as JSON), never on the format alone.
-  `--detail` is verbosity only (`brief|normal|full`);
-  `--shape` (`human|agent|summary`) is the output-projection axis (see
-  Experimental). A small set of commands is **format-exempt** because their
+  `--detail` is `brief|normal|full` (verbosity) or `agent` (the projection of
+  `search`, `curate` and `show`; see Experimental). A small set of commands is **format-exempt** because their
   output is not a result envelope at all: `completions` (shell script source),
   child-process passthrough in `env run` / `secret run`, a bare-path payload
-  from `env path`, and document payloads from `help` (bare, `help agents`, and
+  from `env path`, and document payloads from `help` (bare and
   `help migrate`). The set is declared in
   `src/output/format-exempt.ts`, and
   passing `--format` to one of them warns rather than silently doing something
@@ -250,6 +282,7 @@ remain available across minor releases, but flag names, prompts, and
 proposal-queue shape may shift. Breaking changes will be flagged in the
 CHANGELOG with a migration note.
 
+- **Programmatic API** — `akm-cli/api` (`curate()`, for in-process recall by the akm plugins; see [`docs/reference/api.md`](docs/reference/api.md)). The export list only grows and `curate()`'s parameters and result keep their documented contract; the text it returns is `akm curate`'s agent-shaped output and changes with it. Everything else in the package remains CLI-only.
 - **Improvement loop** — `akm improve` and the proposal noun group
   `akm proposal {extract,new,list,show,diff,accept,reject,reopen,revert,drain}`
   (`extract` and `new` are the former top-level `akm extract`/`akm propose`,
@@ -259,14 +292,15 @@ CHANGELOG with a migration note.
   default and is **review-first**: the lanes that mutate assets without review
   require `experimental.improveAutonomy` — see
   [`akm improve` autonomy](#akm-improve-autonomy--opt-in-in-090).
-  `--auto-accept` was removed in 0.9.0. It is now accepted-and-warned rather
-  than silently absorbed: passing it prints a deprecation warning naming the
-  replacement, and the space-separated form (`--auto-accept 90`) no longer
-  poisons the asset-type positional — its value is discarded with a second
-  warning instead of silently reducing the run to a zero-match no-op. It
-  becomes a hard error in 0.10. The replacement is
+  `--auto-accept` was removed in 0.9.0 and is an unknown flag (a usage error,
+  exit 2) since 0.10. The replacement is
   `akm improve && akm proposal drain --promote --yes`, or a `triage` block
   with `applyMode: "promote"` in your strategy.
+  **Session extraction** (`akm proposal extract` and the improve `extract`
+  process) is Evolving as of 0.10 (#1133): the extract eval (insights saved,
+  routine sessions left empty, planted instructions refused) is its gate. It
+  is Evolving, not Stable, because 0.10 is still settling the improve
+  defaults; what it extracts and its output may still be tuned.
 - **Tasks** — `akm task` subcommand surface (`add | run | sync | doctor |
   history | explain | validate`; no alias, no
   `list`/`remove`/`init`/`enable`/`disable`); task source v4 YAML (typed
@@ -282,14 +316,7 @@ CHANGELOG with a migration note.
   construction** (the excluded data never reaches the command). `akm task
   explain` instead **redacts** secret-shaped input values on a best-effort
   heuristic basis — a value that doesn't match the heuristic can still
-  print unredacted. `akm task validate <path>` (new in 0.9.11) is the same
-  kind of zero-write introspection as `explain`, but takes a bare filesystem
-  path rather than a bundle-qualified ref — it reports whether that ONE file
-  would parse cleanly (`valid`), need `akm migrate apply` first (`blocked`:
-  task v2/v3, or a retired `schedule[].enabled`),
-  fail schema validation (`invalid`), or isn't a task source at all
-  (`not-a-task`) — exactly the diagnostic `akm task sync` would produce for
-  it, before the file is ever wired into a bundle or the scheduler.
+  print unredacted.
 - **Workflow plan** — `akm workflow plan <ref>`, new in 0.9.2: zero-write
   compile+freeze introspection (the canonical step graph, task/child
   expansion, input bindings, and lowering notices for a workflow, without
@@ -300,7 +327,7 @@ CHANGELOG with a migration note.
   both removed; `log` is now a leaf command — the former `list` surface).
 - **Bundles & the workspace model** — installed sources are *bundles*; each is
   recognized by a built-in *adapter* (native Agent Skills, Claude and OpenCode
-  commands/agents, knowledge, YAML workflows, tasks, env/secret files, scripts,
+  commands/agents, knowledge, workflows, tasks, env/secret files, scripts,
   OKF and LLM-wiki knowledge bases). Config is keyed by `bundles` and
   `defaultBundle`. The adapter set, bundle-recognition rules, and the
   `bundles` config shape may still shift; the `okf`, `llm-wiki` and
@@ -357,16 +384,19 @@ for scripted use.
   workflow engine are Experimental from 0.9.28 and throughout 0.10. The 0.10
   series stabilizes the feature and trims what is not useful, then either
   promotes it out of Experimental or removes it if stabilization does not
-  produce a quality feature.
+  produce a quality feature. **Child workflows** (`unit: { workflow: … }`, a
+  step that runs another workflow and returns its last step's output) are the
+  least settled part and are kept only in that simple form; `akm workflow list
+  --children` goes with them.
 - **`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
-  (`--shape human|agent|summary`). `summary` is implemented only on
-  `akm show`; `agent` is implemented on `search`, `show`, and `curate`.
-  Coverage will expand. `--detail` is verbosity only (`brief|normal|full`).
+- **`--detail agent`** — the agent projection, implemented on `search`, `show`,
+  and `curate` (other commands ignore it). Coverage will expand. It replaces
+  `--shape agent`; `--shape` (and `--shape summary`, which only `show` had) is
+  gone in 0.10 and is an unknown flag.
 - **Protected env & secret values** — `env` (a whole `.env` group; key names
   are surfaced for discoverability, values never are) and `secret` (a single
   sensitive value). Values are never written to stdout, the index, or
@@ -378,14 +408,11 @@ for scripted use.
   contradiction edges, and the consolidate journal are observable but
   the algorithm that writes them is tuning across patch releases.
 - **Improve built-in strategies and lanes** — the built-in strategies other
-  than `default` and `consolidate` (`quick`, `reflect-distill`, `thorough`,
-  `catchup`) and the proactive-maintenance and high-salience lanes. 0.10
-  measures each and keeps, folds or removes it (#1094).
-- **Session extraction** — `akm proposal extract` and the `extract` process:
-  what it extracts, its quality gates and its output may change while 0.10
-  measures it (#1094).
+  than `default` and `consolidate` and the proactive-maintenance lane. 0.10 measures each and keeps, folds or removes it
+  (#1094). `quick`, `reflect-distill`, `thorough` and `catchup` were removed
+  in 0.10 (#1130), as were `proactive-maintenance` and the high-salience lane (#1129); a user-defined strategy of the same name keeps working.
 - **Improve tuning config** — `improve.strategies.*.processes.*` (per-process
-  engines, limits, gates, and the anti-collapse / CLS / fidelity knobs) and
+  engines, limits, gates, and the CLS knobs) and
   the `index.*` per-pass config. The 0.9.x series is explicitly still settling
   the design of the improve processes, so **keys in these two families may be
   added, renamed, or dropped in any 0.9.x or 0.10.x release**. The `akm
@@ -401,7 +428,8 @@ mutate assets *without* review require an explicit opt-in:
 akm config set experimental.improveAutonomy true
 ```
 
-Without it, these three lanes are downgraded, and each downgrade is **reported,
+Without it, these three lanes are downgraded (the triage lane only when its
+judgment tier is on), and each downgrade is **reported,
 not silent**: it warns on stderr naming the lane and the key, appends an
 `improve_skipped` event with `reason: "autonomy_gated"`, is counted in
 `akm health`'s improve skip-reason summary, and is listed by `akm task doctor`
@@ -414,7 +442,13 @@ review-first config correctly shows `queue`.
 | --- | --- | --- |
 | `memoryInference` | Writes `.derived.md` children and rewrites parent frontmatter | disabled |
 | memory cleanup | Belief-state frontmatter rewrites, archive moves | analyzed but not applied |
-| `triage` `applyMode: "promote"` | Auto-accepts queued proposals into the bundle | downgraded to `queue` — triage still runs, it just does not auto-accept |
+| `triage` `applyMode: "promote"` **with judgment on** | The judgment tier auto-accepts consolidate promotions into the bundle | downgraded to `queue` — triage still runs, it just does not auto-accept |
+
+A deterministic-only `promote` (triage with judgment off) is **not** a gated
+lane (#1143): the `default` strategy runs it without the opt-in, bounded by
+`maxAcceptsPerRun` (25), through the same deterministic gates as
+`akm proposal drain --promote`. Only a promote that turns the judgment tier on
+needs `experimental.improveAutonomy`.
 
 Consolidation remains enabled with autonomy off: both its passes (promotion,
 and the pair pass's duplicate/subsumed/supersedes judging) only ever emit a
@@ -510,7 +544,7 @@ Shipped from that record: **D1** (`#fragment` section selection),
 gone — `#fragment` is the only section selector), **D4** (conceptId /
 `bundle//` prefix browse), **D5** (`akm bundle` removed), **D6** (open `type`
 set at runtime), **D7** (all six `--format` values everywhere), **D8** (the
-`experimental.improveAutonomy` gate), **D9** (`--auto-accept` warn-and-ignore),
+`experimental.improveAutonomy` gate), **D9** (`--auto-accept` removed, a hard error since 0.10),
 and partially **D10** (an `akm-migrate` binary now exists, though the code still
 lives in this repo). **D3** shipped too, in the end: `akm mv` was removed in
 0.9.0 (see the Renames bullet above), with `scripts/rekey-asset-ref.ts` as the
@@ -519,20 +553,12 @@ Internal replacement for the one capability nothing else covered.
 - **0.10 — `config set`/`config unset` may drop the config dump** in favor of
   a compact `{ok, shape, key}` result; `akm config list` remains the full read.
 - **0.10 — migration extraction.** The migration machinery leaves the CLI for
-  a separately published `akm-migrate` package (see Internal above).
-- **0.10 — `--auto-accept` hard error.** It is currently accepted-and-warned;
-  see the Improvement loop entry.
-- **0.10 — `BundleAdapter.placeNew()` wiring.** The interface declares
-  `placeNew()` as an optional capability method, and 9 of the 11 built-in
-  adapters already implement it (all but `okf` and `website-snapshot`;
-  `claude` and `opencode` inherit theirs from the shared tool-dir factory),
-  but nothing in the write path calls it —
-  writes still resolve through AKM's native flat type→directory table.
-  Placement for every existing bundle is already correct today; this is a
-  deliberately sequenced routing change, not unfinished behavior. See
-  [D12](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md#d12--bundleadapterplacenew-stays-unwired-until-010)
-  for why it is scoped out of 0.9.0. Nothing user-visible changes in 0.10 for
-  this alone.
+  a separately published `akm-migrate` package (see Internal above). The
+  task-source migrator (`task-to-v4.ts`, `task-source-v3-frozen.ts`) already
+  lives with it under `scripts/akm-migrate/migrate/`, out of `src/`.
+- **0.10 — `BundleAdapter.placeNew()` is removed.** Nothing called it; writes use AKM's fixed type→directory table.
+  Writable bundles in a non-akm layout would need per-adapter placement back
+  ([#1163](https://github.com/itlackey/akm/issues/1163)).
 - **1.0 contract freeze** — the `[bundle//]conceptId[#fragment]` ref grammar,
   the supported source model, search behavior, and write-target rules are
   frozen at 1.0. The SDK and in-process plugin story ship on top of that

package/dist/api-node.mjs

@@ -0,0 +1,20 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+// Node entry for `akm-cli/api` (the package `exports` map points the default
+// condition here; the `bun` condition points straight at `api.js`).
+//
+// `api.js` reaches modules that embed `.md`/`.xml` assets through
+// `with { type: "text" }` imports, which Node cannot load without the
+// text-import hook. Those imports are static and hoisted, so the hook must be
+// registered before `api.js` is evaluated: register it, then import `api.js`
+// dynamically. Same reason as `cli-node.mjs`.
+
+import { register } from "node:module";
+
+register("./text-import-hook.mjs", import.meta.url);
+
+const { curate } = await import("./api.js");
+
+export { curate };

package/dist/api.d.ts

@@ -0,0 +1,23 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+// Hand-written declarations for `akm-cli/api` (the build emits no .d.ts).
+// tests/contracts/api-surface.test.ts keeps this file and src/api.ts in step.
+
+export interface CurateOptions {
+  /** Maximum number of curated results (positive integer; the CLI default is 4). */
+  limit?: number;
+  /** Asset type filter, same as `--type`. */
+  type?: string;
+  /** Output format, same as `--format`. Default `"json"`, as in the CLI. */
+  format?: "text" | "json";
+}
+
+/**
+ * Returns exactly the stdout text of
+ * `akm --detail agent -q curate <query> [--limit N] [--type T] --format <format>`,
+ * including its trailing newline. Rejects with the error the CLI would fail
+ * with: its message, and its error code on the `code` property.
+ */
+export function curate(query: string, options?: CurateOptions): Promise<string>;

package/dist/api.js

@@ -0,0 +1,45 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `akm-cli/api` — the one supported programmatic entry point. Everything else
+ * in this package is CLI-only. See docs/reference/api.md for the contract.
+ *
+ * Each export runs the same code path as its CLI command and computes the
+ * document the CLI would print, in-process: no child process, no write to
+ * stdout/stderr, no `process.chdir`, no change to the host's `process.env`,
+ * and no process-level output-mode, quiet or verbose state left changed.
+ */
+import { renderOutput } from "./cli/shared.js";
+import { runCurate } from "./commands/read/search-cli.js";
+import { loadConfig } from "./core/config/config.js";
+import { UsageError } from "./core/errors.js";
+import { withQuiet } from "./core/warn.js";
+import { installLlmUsagePersistenceIfAbsent } from "./llm/usage-persist.js";
+import { resolveOutputMode } from "./output/context.js";
+import { stdoutText } from "./output/stdout.js";
+/**
+ * Returns exactly the stdout text of
+ * `akm --detail agent -q curate <query> [--limit N] [--type T] --format <format>`
+ * including its trailing newline. Rejects with the error the CLI
+ * would fail with: its message, and its error code on the `code` property.
+ */
+export async function curate(query, options = {}) {
+    const format = options.format ?? "json";
+    if (format !== "text" && format !== "json") {
+        throw new UsageError(`Invalid value for --format: ${format}. Expected one of: json|text`, "INVALID_FORMAT_VALUE");
+    }
+    return withQuiet(async () => {
+        // Same startup order as the CLI: config first (an invalid config fails
+        // the call before anything runs), then the output mode from argv + config.
+        const mode = resolveOutputMode(["--detail", "agent", "--format", format], loadConfig().output ?? {});
+        const disposeLlmUsageSink = installLlmUsagePersistenceIfAbsent();
+        try {
+            const curated = await runCurate({ query, type: options.type, limit: options.limit === undefined ? undefined : String(options.limit) }, mode);
+            return stdoutText(renderOutput("curate", curated, { ...mode, format }));
+        }
+        finally {
+            disposeLlmUsageSink();
+        }
+    });
+}