akm-cli 0.9.31 → 0.10.26101002-alpha

package/docs/reference/configuration.md

@@ -95,6 +95,23 @@ kebab-case, at most 63 characters, and cannot start with `akm-`.
 | `llm` | `endpoint`, `model` | OpenAI-compatible chat completions |
 | `agent` | `platform` | A registered dispatch-capable harness |
 
+The registered harnesses (generated from the harness registry; do not edit):
+
+<!-- harness-table:start (generated by scripts/gen-config-schema.ts) -->
+| `platform` | Harness | Binary | Session logs | Model work | Native `agent` |
+| --- | --- | --- | --- | --- | --- |
+| `opencode` | OpenCode | `opencode` | yes | yes | yes |
+| `claude` | Claude Code | `claude` | yes | yes | yes |
+| `opencode-sdk` | OpenCode SDK | in-process | no | yes | yes |
+| `codex` | OpenAI Codex CLI | `codex` | yes | no | no |
+| `copilot` | GitHub Copilot CLI | `copilot` | no | no | no |
+| `pi` | Pi | `pi` | no | no | no |
+| `gemini` | Gemini CLI | `gemini` | no | no | no |
+| `aider` | Aider | `aider` | no | no | no |
+| `amazonq` | Amazon Q Developer CLI | `q` | no | no | no |
+| `openhands` | OpenHands | `openhands` | no | no | no |
+<!-- harness-table:end -->
+
 LLM endpoints must be complete `http://` or `https://` chat-completions URLs
 ending in `/chat/completions`, without userinfo, query, or fragment. API keys
 are symbolic only: `$VAR` or `${VAR}`. AKM resolves them only at dispatch.
@@ -141,6 +158,16 @@ the LLM engine used as that SDK engine's fallback connection. With no
 provider, model and auth from its own configuration. `defaults.llmEngine` is
 not a substitute.
 
+An `opencode` or `opencode-sdk` engine has no setting for the OpenCode major: akm
+detects it. With no `bin`, the engine runs the most recent OpenCode on `PATH`
+(`opencode2`, OpenCode 2's own alias, when present, else `opencode`); with a
+`bin`, it runs that binary. akm runs `<bin> --version` once per binary per
+process and uses the OpenCode 2 or OpenCode 1 adapters to match. OpenCode 1 keeps
+working and logs a warning recommending OpenCode 2. A `--version` akm cannot read
+(or a major it does not know) uses the OpenCode 2 adapters and logs a warning
+with the raw output. To run a particular OpenCode, set the engine's `bin`, e.g.
+`{"kind":"agent","platform":"opencode-sdk","bin":"/opt/opencode1/bin/opencode"}`.
+
 On an engine without `timeoutMs`, model work (an improve process, a quality or
 triage judge, or an index pass) stops after 600 seconds, whatever the engine's
 kind; other work on an agent engine runs until it finishes. An improve stage's
@@ -209,7 +236,7 @@ cannot enforce:
 | LLM | No tools. |
 | `claude` | Read and Edit inside the working directory, and Bash for `akm search` and `akm show` only. akm runs it with `--restricted`, so your user, project and local settings cannot widen that. |
 | `opencode`, `opencode-sdk` | Read, grep and glob in the working directory and the stash, edit in the working directory only, and `akm_search` and `akm_show`, through an injected `akm-model-work` agent. No bash, because opencode cannot stop a redirect such as `akm show x > file` from writing elsewhere. |
-| `codex`, `copilot`, `pi`, `gemini`, `aider`, `amazonq`, `openhands` | Cannot run model work: akm refuses the request before it starts. |
+| Every other `agent` harness | Cannot run model work: akm refuses the request before it starts. |
 
 **The one rule.** Every key model work reads its engine from must name an
 LLM engine or a `claude`, `opencode` or `opencode-sdk` agent engine. Those
@@ -235,7 +262,9 @@ key, the engine and its platform. Other engine keys, `defaults.engine` and
 - opencode model work may read the stash and write only its working directory.
   `akm_search` and `akm_show` come from the akm-opencode plugin (0.9.21 or
   later), which akm does not load: put it in your opencode config
-  (`"plugin": ["akm-opencode"]`). akm turns off the plugin's curation, learning
+  (`"plugin": ["akm-opencode"]` for OpenCode 1; for OpenCode 2 install
+  `akm-opencode-v2` with `opencode plugin add akm-opencode-v2`, see
+  [Use AKM With Any Agent](https://github.com/itlackey/akm/blob/main/docs/guides/use-with-any-agent.md#opencode-plugins-one-package-per-opencode-major)). akm turns off the plugin's curation, learning
   and write gate for these dispatches and keeps its state in akm's state
   directory. The stash is protected from edits only while the temporary
   directory is outside a git repository.
@@ -442,11 +471,21 @@ can select `engine`, `model`, `timeoutMs`, and LLM request overrides:
 
 An improve process's engine follows
 [the one rule](#engines-for-unattended-model-work); an explicit invalid or
-incompatible engine never falls back to another engine. Built-in strategies
-are complete presets. User-defined strategies inherit omitted fields from the
-built-in `default` strategy before applying their own overrides. The built-in
-strategies other than `default` and `consolidate` are Experimental (see
-[STABILITY.md](../../STABILITY.md)): 0.10 measures each and keeps, folds or removes it.
+incompatible engine never falls back to another engine. The built-in strategies
+are `default` and `consolidate`. `consolidate` is a patch that
+is deep-merged onto `default`, and a user-defined strategy of the same name is
+merged on top of that; so every strategy, built-in or user-defined, inherits
+omitted fields from `default`. `quick`, `reflect-distill`, `thorough`,
+`catchup` were removed in 0.10 (#1130): measured, none beat `default` (`thorough`
+and `catchup` added only a judged triage drain, and `catchup` was identical to
+`consolidate`). `proactive-maintenance` was removed too (#1129): its lane now
+lives in `default`. A `improve.strategies.<name>` block with one of those names is
+now an ordinary user-defined strategy that inherits `default`, so it no longer
+carries the old built-in's settings; `--strategy` or `defaults.improveStrategy`
+naming one with no such block fails with an error that names `default`. To keep
+the old judged drain, set `processes.triage` (`enabled`, `applyMode: "promote"`,
+`judgment: true`) in your own strategy. The built-in strategies other than
+`default` and `consolidate` are Experimental (see [STABILITY.md](../../STABILITY.md)).
 
 `processes.triage.judgment` explicitly controls the optional judgment tier.
 Use `true` to enable it, `false` to disable it, or an object with `enabled`,
@@ -457,6 +496,22 @@ the retired `mode` and `profile` keys continue to report their engine migration
 guidance. When enabled, engine selection is judgment → triage → strategy →
 `defaults.llmEngine`, and resolution fails closed if none is available.
 
+The `default` strategy runs triage in `promote` mode with judgment off and
+`maxAcceptsPerRun: 200` (#1143), so the proposal backlog drains through the
+deterministic gates without `experimental.improveAutonomy`. Turning judgment on
+in a promote strategy is what that opt-in gates.
+
+Judgment is off in every built-in strategy, and the judgment tier may accept
+only a consolidate promotion. Retirements, exact fixes and reflect revisions it
+would accept are left for a person. This is measured, not cautious by habit
+(#1132, #1094): with `experimental.improveAutonomy` and judgment over every
+proposal kind, the nightly eval solved 0.49 (gpt-5.6-terra) and 0.53
+(qwen3.8-27b) of its items while harming 14 and 11, and changed 18 and 21 notes
+outside the planted set; the judge accepted unsafe retirements and applied exact
+fixes unreviewed. Judging promotions alone was reasonable: on qwen3.8-27b it
+had precision 0.87 and recall 0.78 and accepted 4.8% of bad promotions; on
+gpt-5.6-terra it was very cautious (precision 1.0, recall 0.17).
+
 ```jsonc
 {
   "improve": {
@@ -557,10 +612,16 @@ off too. Every entry must be a non-empty string, or the config does not load.
 ```
 
 No shipped strategy turns improve-stage session extraction on.
-`proactiveMaintenance` is on only in the `proactive-maintenance` preset; run
-`akm improve --strategy proactive-maintenance` to use that opt-in preset.
-Because strategies inherit from `default`, a preset that omits either process
-also inherits the off value. User strategy overrides
+`proactiveMaintenance` is on in `default` (and in the strategies that inherit
+from it), and off in `quick`, `consolidate`, `catchup` and
+`reflect-distill`. It plans stable assets that have had no feedback: at most
+`maxPerRun` (default 15) per run, only assets not reflected or distilled for
+`dueDays` (default 30), so each comes up at most once a month, and reflect's
+`limit` (25) still bounds the run. A preset that omits either process
+inherits the `default` value; set `processes.proactiveMaintenance.enabled: false` in the
+selected strategy to turn the lane off. A proposal from this lane is never
+accepted by `proposal drain`: it waits for a person (reason
+`proactive-needs-review`, #1147). User strategy overrides
 are applied last, so an explicit `enabled: true` still opts the selected
 strategy in.
 
@@ -789,8 +850,7 @@ explicit destination flag is given and the command isn't already scoped to a
 specific source. It must name a configured bundle; setting it with no
 `bundles` configured, or naming an unconfigured bundle, is rejected at
 `config set` (or config load) time. The full write-target resolution order
-is the command's destination flag (`--bundle` on `remember`/`clone`/
-`improve`, `--target` on `env`/`secret create`) -> `defaultWriteTarget` ->
+is the command's destination flag (`--bundle`) -> `defaultWriteTarget` ->
 working bundle (`defaultBundle`) -> `ConfigError`.
 
 ### Memory scope
@@ -857,7 +917,8 @@ section, an absent key, and an explicit `false` all read identically as off.
 ```
 
 - **`experimental.improveAutonomy`** — gates only the autonomous
-  `memoryInference`, `triagePromote`, and `memoryCleanup` lanes. `akm improve`
+  `memoryInference`, `triagePromote` (a promote with triage judgment on; a
+  deterministic-only promote runs without it), and `memoryCleanup` lanes. `akm improve`
   itself always runs; this only gates mutations without a human in the loop.
   Consolidation is not gated: it remains advisory and emits reviewable
   proposals. `sync.push` is deliberately **not** gated by this key.
@@ -1034,11 +1095,15 @@ network filesystem for the data directory and falls back to `DELETE`.
 
 ## Retired Configuration
 
-`profiles`, `llm`, `agent`, `features`, `stashes`, `defaults.llm`,
-`defaults.agent`, and `defaults.improve` are rejected in 0.9. Recreate the
-configuration using `engines`, `defaults.engine`, `defaults.llmEngine`, and
-`improve.strategies`; AKM deliberately does not infer or rename ambiguous
-profile identities.
+`profiles`, `llm`, `agent`, `features`, and `stashes` are rejected in 0.9.
+Recreate the configuration using `engines`, `defaults.engine`,
+`defaults.llmEngine`, and `improve.strategies`; AKM deliberately does not infer
+or rename ambiguous profile identities. `defaults.llm`, `defaults.agent`,
+`defaults.improve`, `index.stalenessDetection`, the engine settings that used to
+sit under `index.<pass>` (`endpoint`, `provider`, `apiKey`, `baseUrl`,
+`temperature`, `maxTokens`, `capabilities`) and the `feedbackDistillation`
+process (use `processes.distill.enabled`) load like any other unknown key: named
+once by the unknown-key warning, ignored, and dropped by `akm migrate apply`.
 
 `embedding.chunkSize` was never read by anything under `src/` (#954), so a
 config that still sets it is simply ignored — it still loads, unvalidated

package/docs/reference/data-and-telemetry.md

@@ -189,7 +189,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `improve_invoked` | Start of an `akm improve` run | `ref` (scope); `strategy`, `scope`, `dryRun`, `eligibleCount` |
 | `improve_completed` | `akm improve` run finished | run stats |
 | `improve_failed` | `akm improve` run errored | error |
-| `improve_skipped` | `akm improve` left a ref, a lane, or a group of refs out | `reason` (`no_new_signal`, `not_retrieved`, `distill_no_new_signal`, `budget_exhausted`, `budget_exhausted_batch`, `asset_missing_on_disk`, `strategy_filtered_all_passes`, `autonomy_gated`, `engine_unavailable`, `pool_below_min_size`, `consolidation_no_memory_updates`, `below_min_new_sessions`, `derived_memory_reflect_skipped`, `memory_distill_requires_feedback`, `distill_flagged_wrong`, `distill_positive_without_reason`, `distill_deprecated_or_superseded`); `count`, `remaining`, `strategy`, `lane` or `configKey` where they apply |
+| `improve_skipped` | `akm improve` left a ref, a lane, or a group of refs out | `reason` (`no_new_signal`, `not_retrieved`, `distill_no_new_signal`, `budget_exhausted`, `budget_exhausted_batch`, `asset_missing_on_disk`, `strategy_filtered_all_passes`, `autonomy_gated`, `engine_unavailable`, `consolidation_no_memory_updates`, `below_min_new_sessions`, `derived_memory_reflect_skipped`, `memory_distill_requires_feedback`, `distill_flagged_wrong`, `distill_positive_without_reason`, `distill_deprecated_or_superseded`); `count`, `remaining`, `strategy`, `lane` or `configKey` where they apply |
 | `improve_lock_recovered` | Stale improve lock cleared at startup | |
 | `improve_review_needed` | `akm feedback` pushed a high-utility asset's utility below the review threshold — a review-needed escalation is recorded (not a proposal, so it can't accidentally overwrite the asset) | `ref`, `previousUtility`, `nextUtility` |
 | `reflect_invoked` | Start of reflect phase in `akm improve` | `ref`, engine |

package/docs/reference/env-and-secrets.md

@@ -50,7 +50,7 @@ printf '%s' "$TOKEN" | akm secret set secrets/deploy-token
 akm secret run secrets/deploy-token GITHUB_TOKEN -- gh release create v1.0.0
 
 # Write into a specific source instead of the working bundle:
-akm secret set secrets/deploy-token --target team --from-file ./token
+akm secret set secrets/deploy-token --bundle team --from-file ./token
 ```
 
 `env export --out <file>` writes a safe, sourceable `export KEY='value'`
@@ -73,7 +73,7 @@ output and from the search index entirely; the value remains usable via
 
 Env/secret **mutations** (`env create`, `env remove`, `secret set`) choose
 their write destination like every other write command: an explicit
-`--target <source>` wins, else `defaultWriteTarget`, else the working
+`--bundle <source>` wins, else `defaultWriteTarget`, else the working
 bundle. The chosen source must be writable — a non-writable target fails
 with a `ConfigError` before anything is written — and a git-backed writable
 target commits the mutation at a single operation boundary. Reads (`list`,

package/docs/reference/supported-formats.md

@@ -20,7 +20,7 @@ one explicitly. 0.9.0 recognizes 11 formats.
 | `claude` | `CLAUDE.md` as `instruction`; `commands/`, `agents/`, `skills/<name>/SKILL.md` as their matching types | Root `CLAUDE.md` plus at least one of `commands/`, `agents/`, `skills/` | Read-only | Point AKM at an existing Claude Code `.claude` tool directory |
 | `opencode` | Same shape as `claude`, rooted on `AGENTS.md` | `opencode.json`/`opencode.jsonc`, or root `AGENTS.md` plus a canonical plural tool directory | Read-only | Point AKM at an existing OpenCode `.opencode` tool directory |
 | `dotenv` | `env` entries as key names only (never values); `secret` entries as file names only (never content) | Every top-level directory is `env/` and/or `secrets/`, with at least one present | Writable, narrowly — `akm env create`/`env remove`/`secret set` only | A standalone env/secrets-only bundle |
-| `akm-workflow` | Workflow steps, name, description, tags | Either a top-level `.md` file with explicit `type: workflow` frontmatter or a peer top-level GitHub-shaped `.yml` workflow | Writable — `akm workflow create` only | A standalone workflow bundle, one workflow per file |
+| `akm-workflow` | Workflow steps, name, description, tags | A top-level `.md` file with explicit `type: workflow` frontmatter | Writable — `akm workflow create` only | A standalone workflow bundle, one workflow per file |
 | `akm-task` | Task source v4 (`version: 4`) `.yml` sources as type `task`, including local schedules/manual triggers and the exact authored YAML | A top-level `.yml` file accepted by the task source v4 parser (`version: 4`, one `uses`/`run` executable selector, optional top-level `schedule:`) | Read-only | A standalone scheduled-task bundle; `.yaml` is rejected |
 | `llm-wiki` | `raw/` sources as `wiki-source`; `pages/` as their `pageKind` (default `note`), with resolved cross-reference links | Root `schema.md` plus a `pages/` directory | Read-only (author by writing directly into `pages/`; AKM indexes and serves the result) | [Karpathy's LLM-wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — agent-authored reference wikis |
 | `akm` (native) | AKM's own 14 native asset types — see [Asset Types](https://github.com/itlackey/akm/blob/main/docs/reference/asset-types.md) | A `.stash` marker directory, or two-plus native subdirectories, or the fallback when nothing else matches | Fully writable — every AKM-native write command | Your working bundle, and any bundle authored as AKM's own format |
@@ -50,9 +50,8 @@ indexed, scheduled, or executed. See [Tasks](tasks.md).
 
 ## Workflow formats
 
-Workflow sources are the one intentional peer-format case inside the native
-AKM workspace: workflows may be `.md` or `.yml`, and both compile to the same
-source IR. Task sources remain `.yml` only, authored as task source v4. See
+Workflow sources are `.md` and compile to source IR. Task sources are `.yml`
+only, authored as task source v4. See
 [Tasks](tasks.md) and [Workflow Schema](workflow-schema.md).
 
 ## Why this matters

package/docs/reference/tasks.md

@@ -251,10 +251,9 @@ redact: [TOKEN]
   consumer — a native run's status comes from its exit code alone — so
   declaring `output:` on them fails parsing with `TASK_SOURCE_INVALID`
   instead of silently recording a contract nothing enforces.
-- A task source v4 document **can** be the target of a workflow step's
-  `uses: tasks/<ref>` — see the
-  [GitHub-shaped YAML subset](workflow-schema.md#github-shaped-yaml-subset)
-  for how a workflow step's `with:` binds a v4 task's declared `inputs:`.
+- A workflow step cannot target a task: the GitHub-shaped YAML workflow format
+  that carried `uses: tasks/<ref>` was removed in 0.10. A task runs a workflow
+  (`uses: workflows/<ref>`), not the other way round.
 
 ### Input flags
 
@@ -280,10 +279,8 @@ workflow step's own composition uses); for every other target — `run:`
 shell, `scripts/<ref>`, `commands/<ref>` — the values are validated and then
 **discarded**. `akm task run`'s own flags never populate an
 `AKM_TASK_INPUTS` environment variable or a `## Task inputs` prompt block.
-Those two surfaces are a *different* delivery path: they exist only when a
-**workflow step** composes this task through `uses: tasks/<ref>` and a
-`with:` binding, resolved fresh for that step's own dispatch — see
-[`with:` on a task-composed step](workflow-schema.md#github-shaped-yaml-subset).
+Those two surfaces existed only for a workflow step composing a task through
+`uses: tasks/<ref>`, which was removed in 0.10.
 A scheduled run (`schedule[].inputs`, above) reaches the target through this
 same `akm task run` path, so it inherits the identical rule: delivered as
 params for a `workflows/<ref>` target, otherwise validated and discarded.
@@ -401,21 +398,17 @@ for full before/after examples and recovery guidance.
 
 ## Operations
 
-- `akm search --type task` (or its alias `akm task list`) and
+- `akm search --type task` and
   `akm show tasks/<id>` inspect task assets.
 - `akm task explain <ref>` prints a task's declared inputs, resolved target,
   effective execution settings, and schedule bindings without running
   anything — see [`akm task explain`](#akm-task-explain) above.
-- `akm task validate <path>` parses one task file by filesystem path (the
-  file need not live in a configured bundle) and reports the same
-  `valid`/`blocked`/`invalid`/`not-a-task` diagnostic
-  `akm task sync` would produce for it — including sync's own cron-dialect
-  check and its per-schedule-entry input-contract check — without touching
-  the scheduler and without requiring a configured engine, even for a
-  command-kind task. The envelope's own `sourceVersion` field names the
-  file's declared schema version. A version 2/3 file, and a `version: 4`
-  file still carrying a retired `schedule[].enabled`, report `blocked`
-  (exit 1) naming `akm migrate apply`, which converts them.
+- `akm lint --type tasks` reports what `akm task sync` would refuse for a task
+  file: a document that does not parse as task source v4, a version 2/3 file or
+  a `version: 4` file still carrying a retired `schedule[].enabled` (the finding
+  names `akm migrate apply`, which converts them), a cron the local scheduler
+  backend cannot parse, and a schedule entry whose `inputs` leave a required
+  input unsatisfied. It is read-only and needs no configured engine.
 - `akm task add` validates a task source v4 document, writes it, adds its ref
   to local scheduler activation, and syncs its bundle. `--params` renders
   typed `inputs:` declarations instead of a `with:` bag; `--schedule` is

package/docs/reference/website-sources.md

@@ -51,7 +51,7 @@ Drop fetcher modules into:
 ```
 
 `<stashDir>` is the active bundle for the current operation. When a command has a
-resolved write target (for example `akm import --target ...`), akm loads
+resolved write target (for example `akm import --bundle ...`), akm loads
 fetchers from that target bundle before falling back to the built-in website
 scraper.