Moving from AKM 0.10.x to 0.11.0 — draft
This is advance migration guidance published during 0.10.x. It separates the scheduled rollout from changes already on the unreleased 0.11 branch; it does not claim that future commands work in your installed build.
0.10.x adds the replacements; 0.11 removes the old surface. Bring forward run/doctor, scheduler/history diagnostics, asset and typed-task import, search inclusion, show outline/lead, duration and curate budgets, config/source-selector aliases, and command usage metrics. Keep old invocations, defaults, input meanings, and output contracts working throughout 0.10.x. Incompatible defaults, result shapes, schema/reader removals, and scheduler/storage migrations stay in 0.11. Check installed help before changing scripts; the additions listed under Prepare during 0.10.x first ship in 0.10.261119 or 0.10.261120, as each table states. The removal schedule is published now so callers can migrate during the overlap.
For 0.11 developers: Resolve each named TODO(0.11:...) below with verified
syntax, behavior, and supporting versions as the implementation settles. Do not
replace a marker with a guessed flag or remove it without completing its work.
Complete the applicable entries as additions ship in 0.10.x, then verify them
against the 0.11 candidate; the marker names are not a reason to defer the work.
Prepare during 0.10.x
- Inventory CLI calls and JSON readers in scripts, plugins, Desktop, tasks, supervisors, and evaluation tools using the tables below.
- Upgrade to the 0.10.x release that adds the replacements, then migrate callers while their old commands still work.
- Verify results and side effects, not just exit status: preserve inputs, working directories, selected bundles, models, credentials, and run identity.
- Keep the CLI and plugins on compatible versions; a plugin's bundled CLI may
differ from the binary on
PATH.akm upgradenever holds the CLI to a plugin's pin: a plugin running an older bundled akm reports itself stale throughakm doctorand updates with its own release. - Start collecting command/argument usage before removing legacy entry points, and preserve that baseline through the upgrade.
Everything in the next table first ships in 0.10.261119. Desktop ships in
lockstep with akm, so use Desktop 0.10.261119. The plugins pin akm 0.10.261119
from akm-plugins 0.10.261121, which also moves the OpenCode read tools to the
replacements and tolerates the stderr deprecation notices; an older plugin's
bundled CLI may be older than the binary on PATH. Each deprecated form
prints one stderr line per process naming its replacement; --quiet (-q)
silences it.
Added in 0.10.261120 (akm#1623–akm#1630). Each deprecated form below prints one
stderr notice per process naming its replacement, and -q silences it:
| Addition | Replaces |
|---|---|
akm doctor scheduler sync [--bundle] [--rebind] [--dry-run], and with --prune [--yes] [--id] |
task sync, and task prune (a preview unless --yes) |
akm doctor explain <ref> (task ref or id, or workflows/<name>) |
task explain, workflow plan |
Bare akm doctor has a scheduler field |
task doctor |
akm doctor log --task <id> [--bundle] [--limit] |
task history |
akm doctor metrics improve [--run] [--since] |
improve report |
akm doctor metrics assets (same filters and result fields) |
search --by-usage |
proposal extract --sessions <claude|codex|opencode> |
proposal extract --type |
A strategy with processes.proactiveMaintenance.enabled: false, selected with --strategy |
improve --require-feedback-signal |
experimental.learning.{strategies,qualityGate} config aliases |
the same keys under improve.* |
--include type=<custom type> for a custom type in search.defaultExcludeTypes |
(new) |
task history and doctor log --task rows carry the run's trigger (schedule or manual) |
(new) |
CLI usage rows record source agent when a harness is detected, and an optional harness name |
(new) |
cli-usage-store doctor advisory; 9p and CephFS count as network filesystems for the journal-mode fallback |
(new) |
--include type=<custom type> reads search.defaultExcludeTypes from the config
file only, not from extends layers.
Added in 0.10.261119:
| Addition | Available scope |
|---|---|
| Unified execution | akm run <ref> dispatches agents, commands, tasks and workflows through the existing handlers; workflow run ids continue frozen runs. Legacy entries remain. |
| Config file selector | akm --config <file> <command> or AKM_CONFIG_FILE; flag wins, relative paths resolve at invocation, and children inherit an absolute path. Dynamic task/workflow config inputs after the command stay inputs. Old location variables and defaults remain unchanged when absent. credentials.json and models.json always stay in the default config directory (AKM_CONFIG_DIR, else the platform default), never beside the selected file; data/state/cache locations are unchanged. An empty AKM_CONFIG_FILE is warned about once and ignored. |
Independent remember metadata |
--source, --description, and --expires no longer require tags; capture/enrichment behavior is unchanged. |
| Show controls | --outline, --lead, and independent --max-tokens for whole/exact/lead bodies; budgets cover content, template, and prompt, with estimate/truncation metadata. Old forms and unbudgeted reads remain. |
| Curate budget | Opt-in --max-tokens reuses --pack and its output; the unbudgeted default and --pack remain. Conflicting explicit budgets are rejected. |
| Timeout durations | Every --timeout flag, workflow run and run included, takes one grammar: bare N is milliseconds, or ms, s, m, h, d (no month unit). It accompanies every existing --timeout-ms entry point and preserves scope and defaults. |
| Upgrade checksum bypass | akm upgrade --skip-checksum replaces AKM_UPGRADE_SKIP_CHECKSUM, which keeps working through 0.10. |
| Runtime deprecation notices | A deprecated command or flag whose replacement exists prints one stderr line per process naming it; stdout, JSON and exit codes are unchanged and --quiet silences it. Not printed for akm's own scheduler and task invocations. |
| Doctor prompt | doctor prompt <ref> reuses improve <ref> --show-prompt, including task, bundle, strategy and runner selection; both forms are read-only. |
| Doctor entry points | doctor reuses health; doctor metrics, info, log, and judge reuse the existing handlers. Old commands remain. |
improve report, the explain, task-diagnostic and scheduler moves are replaced
in 0.10.261120 (see above).
Execution moves to akm run
| Existing invocation | Migration action |
|---|---|
akm agent <ref> |
Use akm run <ref> for the same agent asset; retain its prompt and execution settings. |
akm command run <ref> or akm command <ref> |
Use akm run <ref>; preserve the command's argument-substitution behavior. |
akm task run <id> --bundle <name> |
Use akm run <qualified-task-ref> with the same task inputs; obtain the ref from AKM rather than guessing it. |
akm workflow run <ref> |
Use akm run <ref> to start the workflow; use the workflow lifecycle commands to resume or inspect an existing run. |
Dispatch is selected by the resolved asset type. This is an entry-point change, not a reason to change a task's inputs, a command's argument string, or an agent's prompt. Scheduled callers must retain their unattended execution behavior.
The replacement first ships in 0.10.261119. The CLI reference records the checked input,
output, exit, timeout, stdin and lifecycle mapping. Keep --prompt /
--prompt-stdin for agent refs, exact --arguments for commands, and declared
input/parameter flags for tasks and workflows (including repeated array values).
Task --bundle and --scheduled retain their meaning. A qualified task ref
retains its owning bundle even when another bundle contains the same task id.
A workflow ref starts a new run; akm run <workflow-run-id> continues the frozen
run. workflow resume, status, list, and abandon remain available through
0.10; 0.11 removes them with workflows (see
Workflows fold into tasks). The new
entry point rejects fragments, unsupported asset types, misapplied options,
extra positional arguments, -- tails, and the old workflow --new no-op.
Agent/command execution selection, command dry-run, task logs/history, workflow
gates/journals, and result/exit contracts use the existing handlers. Scheduler
invocations remain task run --scheduled during the 0.10 overlap. In 0.11 the one minute dispatcher spawns akm run <bundle//tasks/id> --scheduled, and akm migrate apply removes the 0.10 per-task rows.
TODO(0.11:run-removals): Migrate owned callers and scheduler-generated invocations, and remove the deprecated execution entries only in 0.11 after verifying their consumers.
Diagnostics move under akm doctor
| Existing surface | Migration action |
|---|---|
health, task doctor |
Use bare doctor for health and scheduler checks; its scheduler field is task doctor's report (first in 0.10.261120). |
metrics, reporting modes of health |
Use doctor metrics for usage, outcomes, and costs. |
improve report |
Use doctor metrics improve (--run, --since; same usage, routing and cost data). First in 0.10.261120; removed in 0.11. |
search --by-usage |
Use doctor metrics assets (same filters and result fields, no usage recorded). First in 0.10.261120; removed in 0.11. |
improve judge, judge |
Use doctor judge; judge evaluation can still make model calls. |
improve --show-prompt |
Use doctor prompt to inspect a composed prompt without executing the improvement. |
info, log |
Use doctor info and doctor log. |
task explain, workflow plan |
Use doctor explain <ref> for execution-plan inspection (first in 0.10.261120). |
All reporting commands, modes, and human report tables move under doctor in
0.11, including improve's automatic post-run usage/routing table. Preserve the
stored usage and structured run results consumed by evaluators. Ordinary
operation results, lifecycle status, and previews such as --dry-run remain on
their commands. Doctor is an evolving power-user interface; do not parse its human
report layout. Consumers of machine output must use the specific documented
fields they depend on.
TODO(0.11:doctor-contract): Finalize each subcommand's flags, defaults, probes/model-call behavior, report/window filters, project scope, output fields, exit codes, and no-write guarantees where applicable. Inventory reporting outside doctor and complete each move, including automatic human summaries; keep the recorded data and operation-result contracts intact. Migrate health monitors and plugin calls, and document which machine fields have compatibility promises.
Task and import consolidation
Add these replacement paths in 0.10.x and remove the old commands in 0.11.
Keep legacy task/clone behavior throughout 0.10.x, including task add activation
defaults. Preserve task execution and learning-process internals while moving
their CLI entry points. The additive import paths (import --asset-ref and import --type task) first
ship in 0.10.261119.
| Existing surface | Migration action |
|---|---|
task add |
Use import <file> --type task, then task enable for the old default activation behavior; omit enable for the old --disabled case. New typed imports start disabled, updates preserve activation, and old task add stays unchanged until its 0.11 removal. |
task sync |
Use doctor scheduler sync, retaining reconciliation and --rebind behavior. First in 0.10.261120. |
task prune |
Use doctor scheduler sync --prune for owned orphan scheduler entries: a preview unless --yes, with --id to narrow it. First in 0.10.261120. |
task doctor |
Use doctor for scheduler diagnosis (its scheduler field); diagnosis alone does not repair or remove entries. First in 0.10.261120. |
task run |
Use run <task-ref> with the same task inputs and qualified bundle identity. |
task history |
With an id, use doctor log --task <id> (--bundle, --limit) for per-run history, preserving task/bundle identity, timestamps, status, exit information, and log references. The no-id cross-task form has no replacement; doctor metrics gives per-task totals. Both print the run's trigger. First in 0.10.261120. |
task explain |
Use doctor explain <task-ref> with the same inputs and no execution. First in 0.10.261120. |
clone <ref> |
Use import <ref> --asset-ref; preserve rename/overwrite, managed --bundle or unmanaged --dest, asset type, companion files, and provenance. |
Retain task enable, task disable, and the scheduler-facing task dispatch
through 0.10. Their 0.11 form depends on the task format being finalized (see
Workflows fold into tasks).
The new doctor paths wrap the existing 0.10 scheduler first; the one-dispatcher
backend transition stays in 0.11.
Generic search/show remain the task discovery/read surface. Existing document
file/URL/stdin imports remain unchanged, including YAML and ref-shaped paths.
Asset copying requires --asset-ref; typed local task-file import requires
--type task. Both reject document-only flags before reads or writes.
For example, replace akm task add nightly --schedule '0 2 * * *' --command 'echo nightly' with this task file:
version: 4
run: echo nightly
schedule: '0 2 * * *'
Import it with akm import ./nightly.yml --type task, then run
akm task enable tasks/nightly for the old default activation behavior. Omit
enable for the old task add --disabled case. The source is validated and
preserved, including inputs, target details, and metadata. Updates with --force
preserve activation, including legacy hosts without scheduler.enabled.
New tasks remain disabled even if a stale activation or native row names their
previously missing file: legacy activation is captured before writing and the
new ref is excluded. Import changes activation only as needed to keep new tasks
disabled and never installs, updates, or removes native scheduler entries.
import --type task writes scheduler.enabled deliberately: it records the legacy activation first and keeps the new ref out, so a stale scheduler row cannot activate the new task. In 0.10, run doctor scheduler sync after changing an enabled task's native schedule (task sync is Deprecated). In 0.11 the dispatcher reads task files directly and no sync is needed.
--name, --force, and --bundle apply to both new modes. Asset copying also
supports unmanaged --dest, mutually exclusive with --bundle, and delegates
type, companion-file, provenance, and remote resolution to the existing clone
implementation. Task import accepts local files only.
TODO(0.11:task-import): Remove the old task-add and clone surfaces after these replacement paths ship; any incompatible default source-discrimination change waits for 0.11. Verify doctor history filters and scheduler preview/apply, rebind, and owned-orphan handling on the final command tree; update scheduler and supervisor callers.
Workflows fold into tasks
0.11.0 removes workflows, and tasks take over ordered steps. This is the
promote-or-remove decision of akm#1096.
Tasks stay Evolving through 0.11, since the new format first ships in 0.11.0.
Nothing changes in 0.10.x: workflow files,
workflow runs and every akm workflow command work as before.
In 0.11 a task runs one shell line, one agent prompt, or an ordered list of steps. A failed step stops the run, and resuming starts again at that step.
| 0.10 surface | In 0.11 |
|---|---|
| A workflow whose steps run commands or agents | A task with ordered steps. akm migrate apply converts the file. |
A prose playbook in workflows/ that an agent reads |
A command asset. akm migrate apply moves it to commands/. |
A task with uses: workflows/<name> |
The task that replaces the workflow; the wrapper task is no longer needed. |
akm workflow status, list, create, resume, abandon |
Removed. Task run history covers status and listing for new runs, and a failed task run resumes at the step that failed. |
Workflow run history in state.db |
akm migrate apply exports it to a file, then drops the workflow tables. It does not move into task history, and no akm command reads the export. |
| A run that is active or blocked at the upgrade | It cannot continue in 0.11 and is recorded as failed. Finish or abandon it before upgrading; running the task again can repeat side effects. |
Typed agent replies (unit.output on an agent step) |
Kept in a smaller form: a prompt step states what its reply must contain, and akm asks the agent once more when the reply lacks it. Typed values between other steps are not validated. |
Gates, budget, map, gate loops, child workflows |
No replacement. A step's script validates its own input, and a check is another step that fails. |
Task source v4: version, uses, with, typed inputs: and output: |
A simpler task format. akm migrate apply converts v4 files. |
schedule: in a task file |
The schedule that runs moves to each host's config. The file's schedule: may stay as the default that enabling the task applies on a host (see the marker below). |
Try the 0.11 shape now: 0.10.261121 ships steps: in task source v4 as an
Experimental feature (see Steps).
A script that read a workflow step's AKM_INPUTS reads AKM_STEPS there,
keyed by step name; AKM_PARAMS keeps its meaning. Resume is
akm run <task-ref> --resume, and a steps task does not start while its
previous run is alive.
During 0.10.x there is nothing to convert by hand. Where a later step relies on
an earlier step's typed output, make its script check what it receives, since
0.11 validates only a prompt step's reply. To keep old workflow runs readable,
note where akm migrate apply writes the export.
TODO(0.11:task-format): Finalize the 0.11 task syntax and features with the
owner before implementation starts; the draft is on akm#1096.
Then publish the exact v4 mapping here and list every removed key in
STABILITY.md. Settle these points:
- The step keys, and whether the key that lists a task's values is
with:orparams:. - How values and earlier results reach a step. Do not give an existing variable
a new meaning:
AKM_PARAMSkeeps holding the run's values, earlier steps' results get a variable of their own, andAKM_INPUTSis retired so that a script still reading it fails instead of reading the wrong data. - The form of a prompt step's reply check (decided: it stays). A prompt step states what its reply must contain, and akm asks the agent once more when the reply lacks it. A plain retry cannot do this: it reruns the step that failed, so a script that rejects a reply in a later step never reaches the agent.
- What happens when a scheduled task is still running at its next start time
(today a workflow's caller passes
--skip-if-locked). - Retries, the resume entry point, and the
envlist. The Experimentalsteps:of 0.10.261121 field-tests the step keys,AKM_STEPS,expect,retries,--resumeand the overlap rule. It does not cover thewith:/params:rename, theenvlist (a run step loads an env asset withakm env run env/<name> -- <command>) or schedules in host config. - Where schedules live in host config, and what happens to
task enableandtask disable. Direction (owner, 2026-11-13): the task file may keepschedule:as a hint, the default that enabling the task applies on a host; the host's config holds the schedule that runs. - Which remaining v4 keys go.
shellis in use in the field, so either keep it or make its common value the default.
TODO(0.11:workflow-migration): Implement and verify the conversion of
workflow files and playbooks, and the export of workflow run history to a file
before the workflow tables are dropped. Rehearse it on real scheduled workflows, including their scripts, which
read AKM_PARAMS and AKM_INPUTS today. Then update the owned consumers:
- The akm plugins, whose session-start hooks call
akm workflow list --active. - OpenPalm, which calls the workflow CLI and reads and writes task source v4 files.
- fhold, whose task commands write task source v4 files and call
akm task enable. - AKM Desktop's workflow run views.
- Any script that queries the workflow tables in
state.dbdirectly.
Search inclusion
The current 0.10 source supports repeatable --include key=value on search and curate, keeping both old search booleans and their existing semantics until removal in 0.11. Check installed help before migrating:
| Remove in 0.11 | Add in 0.10.x |
|---|---|
--include-proposed |
--include quality=proposed |
--include-sessions |
--include type=session; repeat for any other excluded types the caller intends to restore |
Include expands the eligible categories; filter still narrows the results.
For example, --include type=session --filter team=platform searches ordinary
assets plus sessions, all still restricted to that team and the query. Every
default exclusion needs its own opt-in: a proposed session requires both include
values. Explicit --type, source/project boundaries, date, belief, and metadata
filters remain in force. Unsupported include keys/values must fail clearly;
this is not an arbitrary OR expression or a bypass of access controls.
The reviewed implementation's --include-sessions actually clears all
search.defaultExcludeTypes. Check nondefault exclusion lists when migrating:
--include type=session intentionally restores only sessions.
Project include uses { "quality": "proposed", "type": ["session"] }; an explicit call's include value replaces that whole object. API include: {} clears the selected project's includes. CLI and plugin empty selector lists supply no override. Includes apply to local retrieval; registry retrieval is unchanged. Legacy search booleans remain additive when combined with the new selectors in 0.10.
TODO(0.11:search-include): The selectors first ship in 0.10.261119; remove the old search booleans in 0.11; keep retrieval defaults and learning callers unchanged.
Show simplification and retained time shortcuts
Use the complete show argument review
for retained shared flags. Add --outline, --lead, and independent token budgets
in 0.10.x; keep old modes, formats, and result projections until their 0.11 removal.
| Existing usage | Replacement/cutover |
|---|---|
show <ref> or show <ref>#<fragment> |
Same full-body or exact-fragment read by default |
--context exact / --context lead |
Add --lead in 0.10.x; remove --context in 0.11, with exact remaining the default |
--detail brief |
Add --outline in 0.10.x for headings/slugs without the body; remove the old mode in 0.11 |
--detail normal, full, or 0.10's agent projection |
Keep working in 0.10.x; remove in 0.11 and consume the single documented result shape |
--max-tokens requiring lead mode |
Use it independently for the whole body, fragment, or lead-plus-fragment content |
--max-chars |
Retain through 0.10.x, remove in 0.11; use the documented token-budget estimate or enforce an exact character ceiling in the consumer |
--lead is the replacement for --context lead, and --outline for --detail brief.
--detail brief --lead is a usage error (exit 2), as it asks for a body it does
not show. --detail brief --context lead keeps its 0.10.261118 behavior.
TODO(0.11:show-contract): Finalize outline/lead syntax, budget estimation and truncation fields, invalid combinations, and behavior for non-Markdown/sensitive assets; migrate plugin-generated show hints and consumers of each old projection.
Duration shortcuts stay. Preserve 5m, 12h, 30d, and 3M for --since,
--expires, --window-compare and the timeout: fields of task, agent and
workflow files, exactly as in 0.10.261118; lowercase m is minutes and
uppercase M is a 30-day month, so 3M is 90 days, not a calendar-month
calculation. Keep date/timestamp inputs where already supported. --timeout
has its own grammar in 0.10.x: bare N is milliseconds, or ms, s, m, h,
d, the same for every command, workflow runs included, without changing
effective timeout or learning defaults. The asset files and the other flags
are unified with it in 0.11.
TODO(0.11:durations): Unify the asset-file and --since/--expires grammar with --timeout's, publish the shared unit grammar (--timeout first takes it in 0.10.261119), distinguish elapsed durations from calendar dates, and verify equivalent
milliseconds/shortcuts across timeout, expiry, and reporting-window consumers.
New command and argument usage metrics
Bring forward to 0.10.x: Collect every CLI invocation locally by default,
without sampling, and expose usage analysis through doctor metrics. Existing
asset/model/task records do not provide a complete command-and-argument census;
older periods must remain marked unmeasured rather than backfilled with zeros.
Use additive storage in 0.10.x without requiring the 0.11 storage redesign;
preserve the records/aggregates across that later migration.
| Capture/report | Required behavior |
|---|---|
| Command attempts | Count each invocation once, including subcommands, aliases, help/version, invalid input, early startup errors, and cancellations; retain canonical command identity and recognized invoked spelling. |
| Arguments | Record every supplied flag and positional role, repetition, negation, and argument combinations; distinguish explicit input from defaults and retain the resolved asset type for run. |
| Values and boundaries | Keep allowlisted safe values such as enums/booleans; record presence/type or redaction markers for other values, including free text, credentials, paths, URLs, and child argv. Never store raw argv; arguments after -- and dynamic asset inputs are not AKM flags. |
| Invocation context and result | Record timestamp, CLI version, local instance identity, known caller/source, duration, exit/signal and structured outcome/error category; an unfinished record is not a successful command. |
| Analysis and export | Report command/argument frequency, combinations, per-instance adoption, failures, and duration by version/source/time window; provide stable JSON suitable for combining lab instances without counting overlapping exports twice. |
| Retention and coverage | Preserve release-comparable aggregates through the existing metrics infrastructure after detailed records expire; show collection start, retained window, disabled/unavailable capture, and known gaps separately from zero use. |
Keep collection at the CLI boundary and outside learning feedback/ranking. Use known provenance to separate user/agent demand, scheduled work, internal learning, and audit/evaluation traffic; identify unattributed traffic rather than inferring a human from a terminal or an agent from a pipe. Direct SDK calls are not CLI invocations and must not be implied to be covered. Metrics remain local; lab aggregation uses explicit export, without adding automatic remote transmission.
The additive implementation first ships in 0.10.261119. akm doctor metrics usage --since 30d --format json
reports command and argument counts, combinations, adoption, failures and duration.
Add --export for retained detail; --cli-version, --source, and --until
filter the report. See CLI invocation usage
for schema, redaction, UTC-day windows, overlap deduplication and coverage limits.
The usage tables are cli_usage_* in metrics.db in the data directory, with
schema version 1 kept in cli_usage_meta; detailed rows expire after 30 days
while daily aggregates remain indefinitely. --read-only records nothing (help,
version and info are still counted), and usage.capture: false in the config
file turns capture off. README and
Data and Telemetry say
exactly what is and is not recorded. Failures before module loading and
unavailable storage can be wholly unobserved; SIGKILL cannot produce completion.
In 0.11 the tables stay in metrics.db in the resolved data directory, with
capture starting once that location is known. The tables share no name,
PRAGMA user_version or schema_migrations entry with 0.11's rollup tables;
persisted-data compatibility
states what 0.11 must do, including one known gap: until the first fold migrates a metrics.db that 0.10 wrote, 0.11's health metrics-db check and its metrics-history reader must treat the file as "no day folded yet" instead of failing. The usage rows are kept. The upgrade rehearsal carries metrics.db across.
TODO(0.11:command-usage): Verify preservation of the cli_usage_* tables of metrics.db and their local
instance identity through the 0.11 migration (capture moves after the config read), repeat the CLI coverage tests on the
final command tree.
Learning configuration: change the surface, preserve the processes
Agreed constraint for both releases: Do not change improve or related
automation/learning internals. Preserve process selection/order, eligibility,
prompts and model requests, judgment, acceptance, writes, sync/push, and evaluation
history. The proposal-only default, replacement strategy engine, unified autonomy
policy, and changed setup --learning off semantics are no longer proposed.
Doctor's judge/prompt commands must use the same implementations.
The experimental config aliases first ship in 0.10.261120: experimental.learning.strategies
and experimental.learning.qualityGate mirror improve.strategies and
improve.qualityGate key for key, and the reader folds them into improve.* at
config load. Both old and new keys are accepted without changing effective
settings; when both set a key to different values the new key wins and one
warning names both. The old public paths are removed in 0.11. See the
configuration reference
for the owner's classification of each control. The split below is the 0.11
direction.
| Current control | 0.11 direction |
|---|---|
improve.enabled, ordinary routing/model/time budgets, eventRetentionDays, and useful sync/push controls |
Retain ordinary operating controls and their existing effects, including what learning-off disables. |
improve.strategies.<name> custom process definitions |
Move research definitions under experimental; keep strategy selection and the existing engine, including built-in defaults. |
Strategy process enablement, reflect.qualityGate, reflect.defectFilter, extract triage, indexSessions, and minSessionDuration |
Retain under experimental configuration: checked-in reflect, distill, extract, and bakeoff evaluators use process isolation and these switches. |
improve.processes.<name>, improve.qualityGate, and remaining process tuning |
Audit each override; keep proven operating controls public, move useful research controls, and remove controls without demonstrated value. |
experimental.improveAutonomy |
Preserve its existing gate and default; moving tuning settings must not extend or replace it. |
| Already retired/no-op keys | Remove after checking runtime and evaluator consumers; a field present in an old template is not proof of useful behavior. |
Research-use evidence: the local akm-eval checkout's evals/reflect/src/collect.ts,
evals/reflect/src/defect-filter.ts, evals/distill/src/collect.ts,
evals/extract/src/collect.ts, and evals/bakeoff/src/collect.ts. These establish
consumers, not full 0.11 compatibility; some still emit legacy configuration.
Translate relocated keys at the config boundary into the existing engine inputs. Preserve explicit false/zero/empty values, precedence, and per-run overrides; report conflicting old/new values rather than silently choosing one. The current experimental section describes off-by-default feature gates: new tuning overrides must instead inherit unchanged process defaults when absent. Do not add a blanket experimental switch that disables existing learning. Removing a live override requires an equivalent research path; otherwise it is outside this surface cleanup.
TODO(0.11:sync-mode): Add a per-bundle sync-mode setting that replaces the
strategy sync key. Every akm process calls sync, and sync respects the bundle's
setting. Then remove the strategy sync key. The strategy key stays in 0.10.
TODO(0.11:learning-extends): experimental is host-local, so a base config
pulled in with extends cannot carry experimental.learning. extends is
Deprecated in 0.10.261120 and removed in 0.11, so this conflict goes away with
it: there is no shared base config to carry strategies, and nothing to decide.
Delete this marker once extends is removed.
TODO(0.11:learning-config-parity): List every retained/moved/removed key with
its consumer evidence, exact mapping, defaults, conflict handling, and affected
CLI flags. Compare old and migrated effective plans, model requests, side effects,
and saved evidence using deterministic fixtures and identical-response replay;
update evaluator invocation/config/output adapters without changing cases, prompts,
or scoring. Reconcile existing branch cuts such as improve.stateGc and relocated
inference options against the research baseline before declaring parity.
Other scheduled 0.11 removals and behavior changes
These removals and cutovers are scheduled for 0.11. Prepare during 0.10.x using additive replacements; do not alter old defaults or stdout contracts early. Unspecified replacement syntax remains developer completion work.
| Scheduled 0.11 change | Preparation/migration action |
|---|---|
| Remove general YAML output; restrict Markdown to reports and JSONL to useful streaming operations | Use JSON for structured consumers and text for reading; convert JSON externally where another format is required. |
Remove global --output |
Redirect stdout to a file; keep stderr separate, and use a temporary file plus rename when replacement must be atomic. |
Remove global --detail |
Use the final command-specific budget, result limit, or outline control; update readers to the required fields rather than a verbosity preset. |
Remove remember --auto and --enrich |
No replacement flag and no experimental key; the old flags keep working until 0.11 and print a notice (since 0.10.261120). Enrichment moves to improve: see TODO(0.11:memory-enrichment). |
Remove remember --show-similar |
Retrieve similar material with search or curate separately; the flag prints a notice since 0.10.261120. |
Remove strategy-level limit and consolidate.limit |
Keep --limit and reflect.limit. |
Remove improve.stateGc.collect |
No replacement. |
Remove extract.minNewSessions |
Keep extract.maxSessionsPerRun. |
Remove improve --require-engines |
No replacement; the flag is already a no-op. The eval adapters drop it. |
| Remove old public paths for custom improve strategies and research tuning | Use the experimental.learning.{strategies,qualityGate} aliases (first in 0.10.261120) and migrate without changing selected processes, defaults, strategy resolution, or research treatments. See the planned 0.11 items below. |
Remove improve --require-feedback-signal |
Use a strategy with processes.proactiveMaintenance.enabled: false, selected with --strategy (first in 0.10.261120); no new key. The same refs are planned. One label differs: with the flag a candidate left out is no_new_signal ("no new signal since last proposal"); with the strategy, a candidate with no feedback that search, curate and show did not return in the last 90 days is not_retrieved ("not retrieved inside the usage window"). |
Remove improve --json-to-stdout |
Retain the flag and current stdout contract in 0.10.x; switch to ordinary JSON output with equivalent evaluator-consumed run data in 0.11, preserving persisted results and telemetry. |
| Bulk proposal controls | No change. accept/reject with --generator, --older-than and --max-diff-lines, and proposal drain, both stay; they apply different approval rules. |
Remove upgrade --next |
Use --channel next (--channel latest to return), which switches the CLI and installed plugins together; --next keeps working through 0.10 with a notice. Desktop (desktop/src/lib/server/features/host-tools.ts) still calls upgrade --next and upgrade --check --next through 0.10 and switches to --channel in the 0.11 release (owner, 2026-11-12); account for --channel also switching the plugins and its downgrade guard (--allow-downgrade). |
Remove proposal reject --yes / -y |
Drop the flag. Reject stopped asking for confirmation in 0.10.261121 (proposal reopen undoes a rejection); the flag is ignored with a notice through 0.10. |
Drop the full hints guide (hints --detail full) |
Use the brief guide, akm help <command> and the CLI reference; --detail full is Deprecated in 0.10 and removed with global --detail. |
Remove no-ref interactive agent launch |
Invoke the agent program directly; use akm run <ref> when executing an AKM asset. |
Make curate return packed context by default and remove --pack |
Add opt-in --max-tokens in 0.10.x alongside --pack, preserving the old default until 0.11; use search when only candidates are wanted. |
Make lint fail on errors and remove --fail-on-flagged |
Remove the flag and handle the default nonzero validation result in scripts. |
Replace --timeout-ms with duration-based --timeout |
Use --timeout (first in 0.10.261119); for example, preserve 30000 milliseconds as 30s. |
| Reject invalid legacy values/combinations, including simultaneous quiet/verbose flags | Apply strict validation to new 0.10.x interfaces; remove old fallback/conflict behavior in 0.11. |
Remove extraction's source-harness --type spelling |
Use proposal extract --sessions <claude|codex|opencode> (first in 0.10.261120); --type keeps working through 0.10 with a notice. The selector is separate from the execution harness. |
TODO(0.11:memory-enrichment): Implement an improve-based replacement for
remember --enrich before 0.11.0 stable. Today no improve process sets tags or
the observed date on an existing memory (reflect's patch is limited to
description, when_to_use and title), and akm index makes no model calls.
The smallest candidate is to let reflect's patch carry tags and observed for
memories and to rank untagged memories first in the proactive-maintenance lane,
reusing reflect's judge and proposal queue. Measure it with akm-eval's
remember-enrich cases, and check that the tags improve retrieval, before it is
on by default.
TODO(0.11:plugin-lifecycle): Owner-approved 2026-11-12 after the 0.10.261120 upgrade failures; the evidence is in the notes below. Fix the dependency direction before 0.11.0 stable: plugins depend on akm, and akm never depends on plugins.
akm upgradeupgrades akm only. It stops installing, updating and channel-switching harness plugins and stops editing harness configs. Each plugin updates through its harness's own mechanism: marketplace update for Claude Code and Codex, the npm spec for OpenCode. This removes the plugin half ofsrc/commands/sources/plugin-upgrade.tsand all ofplugin-channels.ts.upgrade --channeland--allow-downgradethen act on the CLI only.- Health keeps one read-only plugin check, the only reader of plugin state.
Per harness it reports the plugin's installed version and the akm it runs,
and names the harness's own update command when that akm is older than this
host's data. Remove the marketplace clones, the
git ls-remoteprobes and the hardcoded remote. - akm-plugins: a plugin uses the installed
akmwhen one exists and falls back to its bundled akm-cli otherwise, so a host with both runs one akm version against its data. - Any reader of akm-plugins artifacts that remains gets a contract test against the real files, run in akm-plugins CI, not a stub.
Why: five root causes, recorded in full in the owner's notes. akm parsed
akm-plugins' private packaging; two akm versions shared one data directory;
upgrade and health kept separate models of the same plugin facts; three
channel systems with two version schemes were compared with each other; and
test fixtures invented formats the plugins do not ship. Since 2026-09-01,
plugin-upgrade.ts took 22 commits, 14 of them fixes.
TODO(0.11:surface-decisions): Publish the exact retired command/flag/key list,
replacement syntax, before/after examples, and the first supporting versions of the additions still
planned for a later 0.10.x (those in 0.10.261119 are listed under Prepare).
Resolve equivalent bulk proposal entry points, research-control mappings,
curate budget/result shape, task authoring, and extraction selector; do not change
learning policy or process behavior as part of those decisions. Every removed command, flag or key fails as a usage
error (exit 2) whose message names its 0.10.x replacement (akm run, akm doctor info/metrics/log/judge, akm import); 0.11 hints that point elsewhere,
such as akm command <ref>, akm judge or task history, are superseded.
Ship these compatible fixes in 0.10.x: remember --source, --description, and
--expires should not require an unrelated tag, and show --max-tokens should
work for whole assets and exact fragments without requiring --context lead.
Both fixes first ship in 0.10.261119. TODO(0.11:compatible-fixes): Document how budgets report omitted or truncated content.
Existing 0.11 branch changes
The following inventory comes from release/0.11.0 at 4b44628eb, not a published
0.11 release. The migration guide at that snapshot
contains the detailed conversion rules. Reconcile that material into the final
guide: its intermediate command, judge, timeout, detail, and diagnostic
spellings are superseded by the staged migration above. Branch-specific storage,
scheduler, format-floor, and reader removals remain 0.11 work; the early additive
CLI rollout does not require backporting those incompatible internals.
| Branch change | Recommended action |
|---|---|
Plain semver from 0.11.0, replacing 0.10 date-based patch numbers |
Update scripts that derive dates from version numbers; normal semver ordering still applies. |
| Conversion floor raised to 0.9.32 | For older persisted data, follow the 0.9.32 stepping-stone migration before proceeding; do not infer compatibility solely from the currently installed binary. |
AKM_CONFIG_DIR, AKM_DATA_DIR, AKM_STATE_DIR, AKM_CACHE_DIR |
Stay Stable in 0.11 (retiring them was a mistake). An environment variable beats config paths, which beats the default; AKM_CONFIG_FILE beats AKM_CONFIG_DIR for the config file. No migration is needed for these, and a relocated host that sets AKM_CONFIG_FILE together with AKM_*_DIR keeps its data, state and cache. |
AKM_BUNDLE_DIR stays retired, with implicit ~/akm and defaultWriteTarget |
Register the bundle and set defaultBundle; use explicit bundle selection or project write defaults where needed, then remove the old variable. |
| Config-relative path resolution | Check relative bundle/storage paths against the config file's directory rather than the caller's working directory. |
Remove the extends config key (Deprecated, first notice in 0.10.261120) |
Copy the inherited keys into each host's own config file; akm config get <key> --show-source shows which come from the base. |
Remove runtime readers for engines, defaults, models.json, secret://, and apiKeyFile |
Run migration; inspect connections/harnesses, credentials, and inlined config before removing old files or sharing the new config. |
Drop config keys, including configVersion, index, setup, and improve/embedding tuning |
Review every discarded value and keep the config backup; audit learning-related removals against the unchanged-internals constraint rather than assuming all were unused. |
| Delete and rebuild old index layouts | Allow time and resources for reindexing/re-embedding, and migrate refs before indexing so usage history remains attached. |
Separate historical metrics into metrics.db |
Include it in backups and verify retained historical totals rather than treating it as a disposable search cache. |
| Reject old task-source formats and abandon undecodable frozen workflow plans | Convert supported task sources and finish, drain, or explicitly restart incompatible workflow runs before switching; restarting can repeat side effects. |
| Replace per-task native scheduler rows with one minute dispatcher | Run the documented migration/sync, confirm only one installation owns the entry, and verify enabled tasks, launcher, bundle identity, and missed-minute behavior. |
| Custom-location and packaged/plugin installations do not own the native scheduler | Have the installation's supervisor invoke task dispatch; do not assume plugin or Desktop execution will install a host scheduler entry. |
Search hits and curate items become results; redundant action/followUp fields disappear |
Update JSON readers and plugins to use results, ref, and registry installRef; verify recall still finds content. |
| Piped JSON becomes compact | Parse JSON structurally; use a formatter when human-readable files are needed. |
./dist/* exports and the workspace tasks namespace disappear; workspace result/config fields change |
Use supported package entry points and update Desktop/API callers using the snapshot's field-by-field inventory. |
| Scheduler/configuration failures use new error codes | Update machine handlers for SCHEDULER_UNAVAILABLE, RETIRED_LOCATION_VARIABLE, and AGENT_NOT_CONFIGURED; avoid matching prose. |
Other removed spellings already on that branch:
| Removed surface | Recommended action |
|---|---|
--engine, improve --require-engines |
Select --connection or --harness as appropriate; use doctor for diagnostics rather than the no-op engine requirement flag. |
Workflow --all-scopes; --allow-dangerous-env-keys; bundle update --yes; registry add --options; task sync --bundle; task add --rebind |
Remove these obsolete/no-op flags; preserve the snapshot's separate task sync --rebind capability under doctor scheduler maintenance. |
task sync --dry-run, migrate apply --dry-run |
Use migrate status for migration/scheduler inspection. |
task history --id <id> |
The snapshot uses a positional task argument; the final target is task-scoped history through doctor log --task <id> (with --bundle), first in 0.10.261120. |
task prune |
Preserve required owned-orphan cleanup through migration/reconciliation as specified above. |
lint --auto-fix |
Use --fix. |
Standalone akm-migrate executable |
Use akm migrate status and akm migrate apply. |
help migrate <version> |
Read the published changelog and migration guide. |
Workflow --new and a task/workflow input named config |
Drop the retired run switch and rename the conflicting input; verify final reserved names after the unified run interface lands. |
Noncanonical extraction durations such as 24H and loosely parsed numeric flags |
Use documented durations and valid numeric values rather than relying on truncation. |
| Legacy scheduler-context descriptors | Reconcile the OS rows from current task definitions before relying on them to fire. |
Since 0.10.261120, setting AKM_SQLITE_JOURNAL_MODE, AKM_UPGRADE_SKIP_CHECKSUM
(during upgrade), AKM_VERBOSE or AKM_DEBUG=1 prints one stderr notice per
process (-q silences it). Environment variables that move: AKM_SQLITE_JOURNAL_MODE is Deprecated with no
replacement and is removed in 0.11 (akm falls back from WAL to DELETE on its own
on a detected network filesystem (NFS, SMB/CIFS, 9p, CephFS, FUSE) such as an Azure Files NFS share, Linux only; keep SQLite on local disk in
ephemeral containers and use snapshots); AKM_UPGRADE_SKIP_CHECKSUM becomes
akm upgrade --skip-checksum; AKM_VERBOSE and AKM_DEBUG become --verbose.
Registry selection, OpenCode cache/CLI settings, Claude config/plugin paths, and
workflow session detection are also affected; see the
snapshot's exact environment mappings.
TODO(0.11:branch-reconciliation): Carry forward every applicable config key,
environment variable, API field, format floor, default, and scheduler behavior
from the branch guide; replace intermediate CLI spellings with the final
run/doctor/import paths and resolve the inclusion, timeout, and show proposals
without dropping duration shortcuts.
Upgrade and verify
- Back up the configured bundles, config/credentials, and persistent databases; record the installed CLI/plugin versions and active workflow runs.
- Resolve active-run compatibility and update callers during the 0.10 overlap period before installing 0.11.
- Upgrade with the old location variables still present so migration can find the existing installation; after a manual package install, run migration before indexing or unattended work.
- Inspect migration results, then update host environment variables, templates, and supervisor commands to the new config and bundle selection.
- Verify the expected installation through doctor, exercise search/show/curate and plugin recall, and check scheduled execution and retained history.
- Verify improvement's migrated settings preserve the prior eligibility, approval, autonomy, and publication behavior before re-enabling unattended jobs.
TODO(0.11:upgrade-rehearsal): Replace this sequence with tested commands and exact supported versions; cover package-manager and self-upgrades, custom paths, plugins, native schedulers, legacy refs, and same-named tasks in different bundles. Close the reviewed legacy-ref history-loss gap before declaring the path safe.
TODO(0.11:rollback-and-runs): State supported downgrade boundaries, the backup restore procedure where downgrade is unsupported, and the handling of workflow runs that are still active at the upgrade (they cannot continue; see Workflows fold into tasks) without implying that a restart is side-effect-free.
Developer completion checklist
- [ ] Resolve every
TODO(0.11:...)marker and publish exact first-supporting versions. - [ ] Confirm additive replacements shipped in 0.10.x with old invocations intact, and every removed surface was listed in
STABILITY.mdbefore 0.11. - [ ] Separate retained core guarantees from evolving doctor/report details and the small named experimental set.
- [ ] Reconcile this guide with
STABILITY.md, the command tree, help, examples, schemas, plugins, and Desktop. - [ ] Verify every old-to-new invocation and behavior change against the release candidate, including removed-command errors.
- [ ] Verify learning config/CLI parity and evaluator compatibility without changing the processes or research measurement contract.
- [ ] Verify complete CLI command/argument coverage, redaction, source separation, and durable usage exports without changing command behavior.
- [ ] Record passing upgrade/platform checks and agent ratification for the exact candidate.
- [ ] Remove draft wording only after the remaining mappings and instructions are complete.