akm docs

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

  1. Inventory CLI calls and JSON readers in scripts, plugins, Desktop, tasks, supervisors, and evaluation tools using the tables below.
  2. Upgrade to the 0.10.x release that adds the replacements, then migrate callers while their old commands still work.
  3. Verify results and side effects, not just exit status: preserve inputs, working directories, selected bundles, models, credentials, and run identity.
  4. Keep the CLI and plugins on compatible versions; a plugin's bundled CLI may differ from the binary on PATH. akm upgrade never holds the CLI to a plugin's pin: a plugin running an older bundled akm reports itself stale through akm doctor and updates with its own release.
  5. 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:

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:

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.

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

  1. Back up the configured bundles, config/credentials, and persistent databases; record the installed CLI/plugin versions and active workflow runs.
  2. Resolve active-run compatibility and update callers during the 0.10 overlap period before installing 0.11.
  3. 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.
  4. Inspect migration results, then update host environment variables, templates, and supervisor commands to the new config and bundle selection.
  5. Verify the expected installation through doctor, exercise search/show/curate and plugin recall, and check scheduled execution and retained history.
  6. 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