akm-cli 0.9.24 → 0.9.25-alpha.2

package/dist/workflows/exec/step-work.js

@@ -13,6 +13,7 @@ import unitPreambleTemplate from "../../assets/prompts/workflow-unit-preamble.md
 import { UsageError } from "../../core/errors.js";
 import { validateJsonSchemaSubset } from "../../core/json-schema.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { withSchemaInstruction } from "../../core/structured.js";
 import { canonicalInputJson, validateInputs } from "../../execution/input-contract.js";
 import { withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
 import { canonicalJson } from "../ir/plan-hash.js";
@@ -248,7 +249,9 @@ function buildStepWorkUnit(ctx, unitId, item, index) {
             // `inputBindings`, when non-empty — see StepWorkUnitContext.taskInputs.
             ...(taskInputs && Object.keys(taskInputs).length > 0 ? { taskInputs } : {}),
             ...(input.gateFeedback ? { gateFeedback: input.gateFeedback } : {}),
-            ...(template.schema ? { schema: template.schema } : {}),
+            // An agent or SDK transport's request lowering appends the schema
+            // instruction itself; a direct-LLM unit carries it in its prompt.
+            ...(template.schema && ctx.runner === "llm" ? { schema: template.schema } : {}),
             instructions: template.instructions,
         });
     const inputHash = computeUnitInputHash(ctx, item);
@@ -373,10 +376,8 @@ export function buildUnitPrompt(input) {
                 ? `\nUnmet criteria:\n${gateFeedback.missing.map((m) => `- ${m}`).join("\n")}`
                 : "")
         : "";
-    const schemaDirective = schema
-        ? `\n\nRespond with ONLY a JSON value matching this JSON Schema (no prose, no code fences):\n${safeJson(schema)}`
-        : "";
-    return `${preamble}\n${instructions}${itemBlock}${inputsBlock}${taskInputsBlock}${gateBlock}${schemaDirective}`;
+    const prompt = `${preamble}\n${instructions}${itemBlock}${inputsBlock}${taskInputsBlock}${gateBlock}`;
+    return schema ? withSchemaInstruction(prompt, schema) : prompt;
 }
 /**
  * Content-derived unit identity (module doc): `<node_id>:<sha256>` for a

package/dist/workflows/exec/unit-dispatch.js

@@ -5,8 +5,7 @@ import { ConfigError } from "../../core/errors.js";
 import { assertFrozenDirectoryContained } from "../../execution/directory-identity.js";
 import { canonicalResolvedExecutionRequest } from "../../execution/resolved-request.js";
 import { buildExecutionFromWire } from "../../integrations/agent/execution.js";
-import { runExecution } from "../../integrations/agent/runner-dispatch.js";
-import { getHarness } from "../../integrations/harnesses/index.js";
+import { runExecution, unwrapHarnessReply } from "../../integrations/agent/runner-dispatch.js";
 /** Lower a frozen common request through its frozen runner only. */
 export function prepareWorkflowExecution(request, prompt = request.prompt) {
     const target = request.frozenTarget;
@@ -107,17 +106,9 @@ export async function dispatchWorkflowExecution(request, feedback) {
             ...(notices ? { notices } : {}),
         };
     }
-    let text = result.stdout;
-    let sessionId = result.sessionId;
-    if (lowered.runner.kind === "agent" && result.ok) {
-        const harness = getHarness(lowered.runner.profile.platform ?? lowered.runner.profile.name);
-        if (harness?.resultExtractor) {
-            const extraction = harness.resultExtractor(result);
-            text = extraction.text;
-            if (extraction.sessionId !== undefined)
-                sessionId = extraction.sessionId;
-        }
-    }
+    const extraction = result.ok ? unwrapHarnessReply(lowered.runner, result) : undefined;
+    const text = extraction?.text ?? result.stdout;
+    const sessionId = extraction?.sessionId ?? result.sessionId;
     return {
         ok: result.ok,
         text,

package/dist/workflows/freeze/step-values.js

@@ -33,7 +33,7 @@ export function targetConcurrency(runner, config) {
     if (runner.kind !== "sdk" || !runner.fallbackConnection)
         return undefined;
     const selected = typeof runner.engine === "string" ? config.engines?.[runner.engine] : undefined;
-    const fallbackName = selected?.kind === "agent" ? (selected.llmEngine ?? config.defaults?.llmEngine) : undefined;
+    const fallbackName = selected?.kind === "agent" ? selected.llmEngine : undefined;
     const fallback = fallbackName ? config.engines?.[fallbackName] : undefined;
     return defaultLlmEngineConcurrency(runner.fallbackConnection.endpoint, fallback?.kind === "llm" ? fallback.concurrency : undefined);
 }

package/docs/reference/cli.md

@@ -517,7 +517,6 @@ kept.
 | `--filter` | `<key>=<value>` | _(none)_ | Scope filter — repeatable. Valid keys: `user`, `agent`, `run`, `channel`. Example: `--filter user=alice --filter channel=ops`. Narrows the result set; ranking is unchanged. |
 | `--include-proposed` | flag | `false` | Include entries with `quality: "proposed"` in the result set. Default search excludes them; `generated` and `curated` quality entries are always included. Unknown quality values warn once and remain searchable. |
 | `--belief` | `all`, `current`, `historical` | `all` | Memory belief filter. `current` keeps active memory beliefs; `historical` keeps contradicted/superseded/archived ones. |
-| `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage events for this successful read |
 | `--include-sessions` | flag | `false` | Include session assets, which are excluded from default results via `config.search.defaultExcludeTypes` |
 | `--format` | `json`, `jsonl`, `yaml`, `text`, `md`, `html` | `json` | Output format |
 | `--detail` | `brief`, `normal`, `full` | `brief` | Output verbosity level |
@@ -593,7 +592,6 @@ akm curate "learn the release workflow" --from all --format text
 | `--type` | `skill`, `command`, `agent`, `knowledge`, `instruction`, `workflow`, `script`, `memory`, `env`, `secret`, `lesson`, `task`, `session`, `fact`, `any` | `any` | Filter curated results by asset type |
 | `--limit` | number | `4` | Maximum curated results |
 | `--from` | `local`, `registry`, `all` | `local` | Where to search before curating |
-| `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage events for this successful read |
 
 `akm curate` takes the top `--limit` hits of one search, in search order, and
 enriches each with a preview, run details and up to two support refs: the
@@ -623,7 +621,6 @@ curated like any other.
 every prompt: it only ever reads the index as it currently stands (the same
 non-blocking `ensureIndex()` path `search` uses) and never waits on or
 contends with a full `akm index` rebuild in progress.
-Use `--no-track-usage` when this inspection must not record usage events.
 
 ### show
 
@@ -631,9 +628,6 @@ Display an asset by ref. On a markdown document `#fragment` selects one
 section by heading slug (falling back to case-insensitive heading text); an
 unmatched fragment lists the available slugs.
 
-Successful reads record local usage events by default; pass
-`--no-track-usage` to suppress them.
-
 ```sh
 akm show scripts/deploy.sh
 akm show skills/code-review
@@ -662,7 +656,6 @@ akm show memories/retro --filter user=alice --filter agent=claude
 | `--max-chars` | positive integer | `3200` for `lead` | Hard contextual content budget in characters; requires `--context lead` and is mutually exclusive with `--max-tokens`. |
 | `--max-tokens` | positive integer | _(none)_ | Approximate contextual budget using four characters per token; requires `--context lead` and is mutually exclusive with `--max-chars`. |
 | `--filter` | `<key>=<value>` | _(none)_ | Repeatable scope filter (`user`, `agent`, `run`, `channel`). |
-| `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage events for this successful read. |
 
 `meta` is not an asset type — `[<origin>//]meta[:<name>]` direct-reads a
 human-authored orientation doc from a bundle's optional `.meta/` directory
@@ -2326,7 +2319,8 @@ or inference payload was selected.
 
 **Platform-specific dispatch:** akm uses a platform builder to construct the
 CLI argv for each engine's harness platform. `platform: "opencode"` engines emit:
-`opencode run [--system-prompt "..."] [--model opencode/claude-opus-4-7] "<prompt>"`.
+`opencode run [--model opencode/claude-opus-4-7] "<prompt>"`. `opencode run` has
+no system-prompt option, so akm composes a persona into the prompt.
 `platform: "claude"` engines emit:
 `claude [--system-prompt "..."] [--model claude-opus-4-7] --print -- "<prompt>"`.
 Agent engines may set `bin`, `args`, `workspace`, `model`, and `timeoutMs` in
@@ -2430,6 +2424,7 @@ akm improve lessons/my-lesson --show-prompt --format text # print the composed r
 akm improve report                     # LLM usage/routing report for the most recent real run
 akm improve report --run <id>          # ...for one specific improve_runs id
 akm improve report --since 7d          # ...aggregated over every real run started in the last 7 days
+akm improve judge < revision.json      # reflect's quality judge on one revision; writes nothing
 ```
 
 | Flag | Description |
@@ -2446,7 +2441,7 @@ akm improve report --since 7d          # ...aggregated over every real run start
 | `--strategy <name>` | Override the active improve strategy (a built-in or entry under `improve.strategies`) |
 | `--json-to-stdout` | Also emit the full persisted JSON result on stdout for a live run. Without this flag, stdout stays empty. Dry-runs always emit their result and are never persisted. |
 | `--skip-if-locked` | If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with "already running" (exit 75, `TransientError`, code `IMPROVE_LOCK_HELD` — field follow-up to #948: two legitimate `improve` invocations colliding on this lock is ordinary, retryable contention, not a broken config file). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress. |
-| `--require-engines` | Abort (exit 78, before any indexing, lock, or log side effect) if the active strategy would enable a process whose engine or credential cannot be resolved in this process's environment, OR whose endpoint fails a bounded reachability probe — the same probe `akm health`'s `default-llm-engine`/`configured-engines` checks run, once per distinct endpoint. Without this flag, improve degrades gracefully: it skips the affected processes and reports them in the result's `skippedProcesses`. Recommended alongside `--skip-if-locked` for scheduled runs, since the operator's own shell can pass config validation while a scheduler's stripped-down environment (see #953) cannot. |
+| `--require-engines` | Abort (exit 78, before any indexing, lock, or log side effect) if the active strategy would enable a process whose engine or credential cannot be resolved in this process's environment, OR whose endpoint fails a bounded reachability probe — the same probe `akm health`'s `default-llm-engine`/`configured-engines` checks run, once per distinct endpoint. An agent engine's check is that its binary is on PATH, and an `opencode-sdk` engine's is both its binary and, when it sets `llmEngine`, that LLM fallback's endpoint. Without this flag, improve degrades gracefully: it skips the affected processes and reports them in the result's `skippedProcesses`. Recommended alongside `--skip-if-locked` for scheduled runs, since the operator's own shell can pass config validation while a scheduler's stripped-down environment (see #953) cannot. |
 | `--show-prompt` | Print the composed reflect prompt (#952) for one asset and exit — before any lock, index write, or engine dispatch. Requires a fully-qualified asset ref as the scope (`akm improve lessons/my-lesson --show-prompt`); rejected with a type or whole-bundle scope. The default output format is JSON, which carries the prompt as a `prompt` field (escaped into one line) alongside the resolved `engine`/`engineKind`; pass `--format text` to print the prompt itself, unwrapped and readable by eye. |
 | `--sync` / `--no-sync` | Commit (and optionally push) the git-backed primary bundle when the run finishes. Default: on for git-backed bundles (per profile config). |
 | `--push` / `--no-push` | Push after the end-of-run sync commit when writable with a remote configured. `--no-push` commits only, skipping the push. Default: per profile config (`true`). `sync.push` stays outside the autonomy gate — this is a per-run opt-out, not a default change. |
@@ -2582,7 +2577,7 @@ table: one row per improve process (`reflect`, `distill`, `consolidate`,
 `memoryInference`, `extract`, `validation`, `triage`,
 `proactiveMaintenance`), plus a `triage.judgment` row when the strategy
 configures a judgment engine. Each row carries `enabled`, the resolved
-`engine`/`model` (llm-backed processes only) and `engineKind`, this process's
+`engine`, its `model` (when the engine has an LLM connection) and `engineKind`, this process's
 own lowering `notices`, and — for reflect/distill/consolidate only —
 `eligibleRefs`, the count of this run's `effectiveRefs` the process would act
 on (`shouldSkipRef`'s allowedTypes/excludeRefPrefixes (reflect only)/
@@ -2607,7 +2602,9 @@ default probe-on behavior) to check whether a named engine actually answers.
 builds the exact prompt reflect would send for one asset — the same source
 resolution, runner selection, feedback/schema-hint/related-lesson/rejected-
 proposal gathering `akm improve`'s live reflect step uses — and prints it
-without reading a credential, so it never calls an engine. Add
+without reading a credential, so it never calls an engine. An LLM engine
+receives the reply's JSON Schema as `response_format`, and an agent engine as
+an instruction that dispatch appends to this prompt. Add
 `--format text` (the default JSON/yaml envelope escapes the prompt into one
 line, which defeats a by-eye read) to confirm by eye that recent feedback is
 framed as an unverified report to investigate (never a fact to insert
@@ -2619,7 +2616,7 @@ destination than `memory`.
 
 #### improve report
 
-`akm improve report` (#944) answers "which engine did each LLM-backed process
+`akm improve report` (#944) answers "which engine did each model-calling process
 use this run, how much did it cost, and which enabled processes made zero
 calls (and why)" without hand-written SQLite against `state.db`. It is a
 `scope` value, not a subcommand — `report` is not, and will never be, a real
@@ -2632,7 +2629,7 @@ field on the result (`result_json` in `improve_runs`, and in the
 `byProcessEngineModel` is a cross-tab of this run's own `llm_usage` events
 (#576) — one row per distinct `(process, engine, model)` triple, each with
 `calls`, `failures`, `promptTokens`, `completionTokens`, `totalTokens`,
-`reasoningTokens`, and `totalDurationMs`. `noCalls` lists every LLM-backed
+`reasoningTokens`, and `totalDurationMs`. `noCalls` lists every model-calling
 process (`reflect`, `distill`, `consolidate`, `memoryInference`,
 `extract`, `validation` — not `triage`/`proactiveMaintenance`,
 which never make an attributable LLM call themselves) the active strategy
@@ -2657,6 +2654,17 @@ that run's own `llm_usage` events instead of erroring, sets `noCalls` to `[]`
 `notes` entry saying so rather than fabricating precision the old row can't
 support.
 
+#### improve judge
+
+`akm improve judge` runs reflect's quality judge on one revision and prints its
+verdict, for testing a judge engine on revisions whose right answer you know. It
+reads `{"source": "...", "candidate": "...", "feedback": "...", "ref": "..."}` JSON
+from stdin (`feedback` and `ref` are optional; `ref` names the revised asset,
+which a judge on an agent engine may read), judges with the engine the strategy's
+`processes.reflect.qualityGate.engine` names (`--strategy` picks the strategy),
+and prints `{ engine, pass, score, reason, criteria }` with the gate's prompt and
+pass rule. A `score` of `-1` means the judge gave no verdict. It writes nothing.
+
 ### proposal
 
 Manage the proposal queue. The canonical grammar is `akm proposal <verb>`:
@@ -2706,7 +2714,7 @@ akm proposal extract --type claude --location /custom/path --session-id <id>
 | `--dry-run` | Show candidates without queuing proposals. |
 | `--force` | Re-process sessions even if they were already extracted and have no new events. Default: skip already-seen sessions. |
 | `--timeout-ms <ms>` | Per-session LLM timeout in ms (default `600000`). |
-| `--engine <name>` | Named LLM engine for this invocation. Mutually exclusive with `--strategy`. |
+| `--engine <name>` | Named engine for this invocation: an LLM engine, or a `claude`, `opencode` or `opencode-sdk` agent engine. Mutually exclusive with `--strategy`. |
 | `--strategy <name>` | Improve strategy supplying extract behavior and engine. Mutually exclusive with `--engine`. |
 
 `--type` and `--auto` are mutually exclusive; one of them is required.
@@ -2721,8 +2729,10 @@ dropped — a foreground polling daemon in a one-shot CLI); the shipped
 `core/extract.yml` cron template (`akm proposal extract --auto` on a
 schedule) is the answer.
 
-Requires an LLM engine: pass `--engine`, select a `--strategy` whose
-`processes.extract.engine` is set, or configure `defaults.llmEngine`.
+Requires an engine that can run unattended model work (an LLM engine, or a
+`claude`, `opencode` or `opencode-sdk` agent): pass `--engine`, select a
+`--strategy` whose `processes.extract.engine` is set, or configure
+`defaults.llmEngine`.
 
 **Output.** `ok` means the command ran to completion — it is `true` even when
 every session was skipped (an unreachable LLM engine included); it does not
@@ -2732,7 +2742,7 @@ harvest" branch on `skipReasons`, `warnings`, or `sessionsProcessed` /
 
 | Field | Description |
 | --- | --- |
-| `engine` | Resolved LLM engine name for this run. Absent only when extract is disabled by the selected improve strategy (the run returns before an engine is resolved). |
+| `engine` | Resolved engine name for this run. Absent only when extract is disabled by the selected improve strategy (the run returns before an engine is resolved). |
 | `engineKind` | `"llm"`, `"sdk"`, or `"agent"` — the kind of runner `engine` resolved to. Same absence condition as `engine`. |
 | `skipReasons` | Per-`skipReason` count across `sessions[]` (e.g. `{ "llm_unavailable": 25 }`). Present only when `sessionsSkipped > 0`. |
 | `warnings` | Includes one aggregate line per infrastructure skip reason that fired (`llm_unavailable`, `read_failed`, `exception`, `locked_concurrent`) — e.g. `25 of 25 sessions skipped: llm_unavailable (engine "default")` — so an engine outage is visible without inspecting `sessions[]`. Session-content skips (`already_extracted`, `too_short`, `triaged_out`) are counted in `skipReasons` but never produce a warning line. |
@@ -2755,11 +2765,24 @@ akm proposal new skill code-review --path team --task "PR-style review skill"  #
 | `--path` | Relative subdirectory under the type dir to place the proposed asset in (e.g. `release`). The filename comes from `<name>`. |
 | `--task` | Inline task text |
 | `--file` | Read task text from a UTF-8 file |
-| `--engine` | Override the default execution engine |
+| `--engine` | Override the default execution engine. Any kind works: an LLM engine, an agent CLI or `opencode-sdk` |
 | `--timeout-ms` | Override the selected engine timeout for this call |
 
 Exactly one of `--task` or `--file` is required. Emits `propose_invoked`.
 
+Every engine kind returns the proposal the same way: as one JSON object on
+stdout with the asset's `ref`, its full `content` and a self-rated
+`confidence`. akm sends the object's JSON Schema with the request, as
+`response_format` to an LLM engine and as an instruction at the end of the
+prompt to an agent engine (codex also gets it as `--output-schema`). akm
+captures the reply; an agent CLI runs headless, with no live terminal session.
+A harness's own JSON envelope, such as claude's
+`--output-format json` result, is unwrapped first.
+A reply that is not a valid proposal gets one corrective retry that says what
+was wrong. If that reply is not valid either, the command exits 1 with
+`reason: "parse_error"` and an error that names the engine, for example
+`Engine "local" reply was not valid proposal JSON after 2 attempts: …`.
+
 **Prompt-task `timeoutMs`:** a version-2 prompt task may set `timeoutMs` to
 override its selected engine timeout. Set it to `null` to disable the timer, or
 to a positive integer (milliseconds) to apply a task-specific limit.

package/docs/reference/configuration.md

@@ -116,9 +116,31 @@ settable via `extraParams`. A response with reasoning tokens despite
 `enableThinking: false` triggers a runtime warning and the `akm health`
 `thinking-control` advisory.
 
-An agent engine may set `bin`, `args`, `workspace`, `model`, and `timeoutMs`.
-Only `platform: "opencode-sdk"` may set `llmEngine`; it names
-the LLM engine used as that SDK engine's fallback connection.
+When a call asks for JSON that matches a schema, an LLM engine sends the schema
+as `response_format` (`json_schema`, strict) unless the engine sets
+`supportsJsonSchema: false`. If the endpoint rejects it with a 4xx other than
+429, AKM retries once without `response_format` and stops sending it to that
+endpoint and model for the rest of the process. An agent engine receives the
+schema as one instruction at the end of its prompt (`Respond with ONLY a JSON
+value matching this JSON Schema (no prose, no code fences):` followed by the
+schema), plus the harness's own schema channel where it has one (codex
+`--output-schema`).
+
+An agent engine may set `bin`, `args`, `workspace`, `model`, and `timeoutMs`;
+it takes no inference of its own (see
+[Inference on an agent engine](#inference-on-an-agent-engine)). Only `platform: "opencode-sdk"` may set `llmEngine`; it names
+the LLM engine used as that SDK engine's fallback connection. With no
+`llmEngine`, an SDK engine has no fallback connection and opencode resolves
+provider, model and auth from its own configuration. `defaults.llmEngine` is
+not a substitute.
+
+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
+reply that the stage cannot read gets one corrective retry. Reflect holds its
+reply to its own contract the same way on every engine kind: a reply that is not
+the JSON object of reflect's schema gets one repair turn, and one still invalid
+fails with `parse_error`.
 
 Executable assets may request tools, but the request is not authority. Configure
 the host-local `execution.allowedTools` list to define the ceiling; `"*"` is an
@@ -132,6 +154,85 @@ client with no dependencies — it spawns `opencode serve` and talks to it — s
 the npm dependency alone does not make the platform usable. Install the binary
 with `npm i -g opencode-ai` or opencode's own installer.
 
+### Inference on an agent engine
+
+An agent engine sets no inference of its own. For `opencode`, set it on the
+model in your own opencode config, which akm leaves as it is. akm carries
+inference (`temperature`, `reasoningEffort`, `enableThinking`, `maxTokens`,
+`contextLength`) into opencode only where it writes opencode's config itself:
+
+- **Model work on `opencode` and `opencode-sdk`:** an improve process's `llm`
+  overlay becomes the options of the `akm-model-work` agent that runs the
+  dispatch, so opencode's own title call on the same model keeps its defaults.
+- **An `opencode-sdk` engine's `llmEngine` fallback:** the model akm declares for
+  it under `akm-custom` carries the fallback's inference and the request's.
+  `maxTokens` and `contextLength` become `limit.output` and `limit.context`, and
+  only together: opencode refuses half a `limit`.
+
+Inference from an asset, a workflow's `llm:` or a `models.json` alias reaches an
+LLM engine. On an agent engine it is reported as an `untranslated-field`
+notice and dispatch continues; model work's agent carries `temperature`,
+`reasoningEffort` and `enableThinking` without one.
+
+Reasoning effort has one word in a request, `reasoningEffort`. `effort`, as a
+`models.json` alias or an asset's `effort:` frontmatter spells it, is read as
+`reasoningEffort` wherever layers are merged, so an LLM engine sends it as
+`reasoning_effort`.
+
+### Engines for unattended model work
+
+Unattended model work is the work akm hands a model with no one watching:
+- the improve processes (reflect, distill, consolidate, memory inference,
+  extract, and validation's repair);
+- the quality, triage and retrieval-gate judges;
+- index passes;
+- `akm remember --enrich`.
+
+It runs on any engine kind under one tool policy. The model may read, edit
+files only inside a scratch working directory that akm creates for the
+dispatch and removes after it, and run `akm search` and `akm show`. The
+stash stays read-only to it: what model work changes reaches the stash only
+as a proposal, through the review queue.
+
+Each engine enforces as much of the policy as it can, and grants nothing it
+cannot enforce:
+
+| Engine | What the model gets |
+|---|---|
+| 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. |
+
+**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
+keys are:
+- `defaults.llmEngine`;
+- `index.defaults.engine` and `index.<pass>.engine`;
+- `improve.strategies.<name>.engine`;
+- `improve.strategies.<name>.processes.<process>.engine`;
+- an enabled `processes.triage.judgment.engine`;
+- `processes.<process>.qualityGate.engine`.
+
+A config that breaks the rule fails to load, with an error that names the
+key, the engine and its platform. Other engine keys, `defaults.engine` and
+`workflow.judgeEngine`, may name any configured engine.
+
+**Further details:**
+- A model-work dispatch builds its own command, so the engine's `args` do not
+  apply to it, except a `--model` they name, and neither does its `workspace`.
+- An improve process's `llm` overlay reaches the `akm-model-work` agent on
+  `opencode` and `opencode-sdk` (see
+  [Inference on an agent engine](#inference-on-an-agent-engine)); on any other
+  agent engine it is reported as `untranslated-field` notices, not errors.
+- 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
+  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.
+
 ### Model-map files
 
 AKM ships an immutable `models.json` package asset with three intent aliases:
@@ -176,7 +277,8 @@ profile may omit `model` when the installed layer already supplies it, as the
 partial Claude override above does. After overlay, every alias/engine entry
 must have a usable model. Unknown profile fields are rejected; JSON-safe
 fields inside `inference` are preserved for engine adapters to lower
-optimistically.
+optimistically. An `inference.effort` is read as `reasoningEffort`
+(see [Inference on an agent engine](#inference-on-an-agent-engine)).
 
 A profile's `engine` field (0.9.15, #946) borrows a column's `model` (and, for
 an `llm`-kind engine, its inference defaults) from a configured
@@ -265,16 +367,24 @@ the embedded copy, and release tests pin copied bytes to `src/assets/models.json
 The health check passes when the optional user file is absent and warns with
 its path and JSON location when the user file is unreadable or invalid.
 
-`defaults.engine` names an LLM or agent engine. `defaults.llmEngine` must name
-an LLM engine. There is no first-engine fallback: an unset `defaults.engine`
+`defaults.engine` names an LLM or agent engine. `defaults.llmEngine` names the
+default engine for unattended model work, so it follows
+[the one rule](#engines-for-unattended-model-work). There is no first-engine
+fallback: an unset `defaults.engine`
 never resolves to some arbitrary entry in `engines`. It resolves instead to a
 synthesized, config-free `opencode-sdk` engine when the `opencode` binary is on
 PATH — announced once per run, and preempted by any `opencode-sdk` engine you
 configure yourself. Naming an engine that is not configured is always an error
 and is never rescued by that fallback.
 
+`defaults.llmEngine` is not an `opencode-sdk` engine's fallback connection. An
+SDK engine gets an LLM fallback only from its own `llmEngine`, so the
+synthesized engine, which sets none, runs on opencode's own provider, model and
+auth.
+
 Index passes select engines through `index.defaults.engine` or
-`index.<pass>.engine`. Per-pass `model`, `timeoutMs`, and `llm` fields are
+`index.<pass>.engine`, which follow
+[the one rule](#engines-for-unattended-model-work). Per-pass `model`, `timeoutMs`, and `llm` fields are
 invocation overrides; `enabled: false` disables that pass. Connection fields
 such as `endpoint`, `provider`, `apiKey`, and `apiKeyFile` belong only on
 named engines.
@@ -323,7 +433,8 @@ can select `engine`, `model`, `timeoutMs`, and LLM request overrides:
 }
 ```
 
-LLM-only improve processes require an LLM engine; an explicit invalid or
+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.
@@ -359,11 +470,13 @@ each process's LLM-as-judge quality gate. Each is on unless it sets
 `enabled: false`, and each follows only its own switch. A reflect revision
 that changes the body is never auto-accepted; when the judge passes it, it
 waits for review. With the gate off, it waits for review too. The judge is the
-process's own LLM engine, or `defaults.llmEngine` when an agent generates.
-`engine`, `model`, `timeoutMs` and `llm` give the gate a judge of its own,
+process's own engine when that is an LLM engine, or the `defaults.llmEngine`
+engine when an agent generates. `engine`, `model`, `timeoutMs` and `llm` give the gate a judge of its own,
 resolved over the process's settings the way `triage.judgment` resolves over
-triage's. A gate whose settings resolve to no LLM engine fails before anything
-is generated; it never falls back to another engine. The judge runs at
+triage's. The judge may be any engine that follows
+[the one rule](#engines-for-unattended-model-work). A gate whose settings
+resolve to no engine fails before anything is generated; it never falls back
+to another engine. The judge runs at
 temperature 0 with thinking off unless its engine sets `enableThinking: true`.
 Thinking is slow: on a 27B llama.cpp server, a thinking judgment took a median
 of 30–67 s and up to about 3 minutes, against about 5 s without.
@@ -392,6 +505,46 @@ judge's engine at the server directly.
 }
 ```
 
+`processes.reflect.defectFilter` sets the wording of the checks reflect runs
+before the judge. With the quality gate on or off, reflect refuses a revision
+that adds placeholder text, talks about its own edit, or copies frontmatter into
+its body: no proposal, and no judge call. Each rule counts only what the
+revision adds to its source, so wording the asset already had and kept is not
+held against it. Each of the three lists is optional. A list you set replaces
+that rule's default list, and `[]` turns the rule off.
+
+| List | Rule | Default |
+|---|---|---|
+| `placeholders` | `placeholder_added` | `please confirm`, `please verify`, `to be confirmed`, `to be determined`, `to be verified` |
+| `metaCommentary` | `meta_commentary_added` | `feedback signal`, `feedback signals`, `feedback indicate`, `feedback indicates`, `feedback suggest`, `feedback suggests`, `feedback ask`, `feedback asks`, `feedback says`, `feedback report`, `feedback reports`, `feedback request`, `feedback requests`, `this revision`, `the source asset`, `the source note`, `the source memory`, `the original asset`, `the original note`, `the original memory`, `the original version of this`, `quality gate rejected`, `proposal rejected` |
+| `frontmatterKeys` | `frontmatter_copied_into_body` | `sources`, `updated`, `inferenceProcessed`, `captureMode`, `beliefState`, `xrefs`, `contradictedBy`, `outcomeData`, `orderedActions`, `generated`, `verified`, `description`, `when_to_use`, `tags`, `searchHints`, `quality`, `salience`, `salienceInputs`, `lint_skip`, `type` |
+
+`placeholders` and `metaCommentary` entries are plain phrases, not patterns:
+whole words, in any case, with any run of whitespace between words.
+`frontmatterKeys` entries are exact key names: a line outside a code fence that
+starts with `key:` counts. The rule also refuses a `sources`, `xrefs` or
+`contradictedBy` value copied into the body; `frontmatterKeys: []` turns that
+off too. Every entry must be a non-empty string, or the config does not load.
+
+```jsonc
+{
+  "improve": {
+    "strategies": {
+      "nightly": {
+        "processes": {
+          "reflect": {
+            "defectFilter": {
+              "placeholders": ["please confirm", "to be confirmed", "[draft]"],
+              "frontmatterKeys": []
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 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.

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

@@ -245,9 +245,8 @@ engagement, feedback signals, stable refs, and timestamps. It never leaves the
 machine unless you explicitly copy the database or send derived content to a
 configured endpoint.
 
-Successful `search`, `curate`, and `show` commands record usage by default.
-Pass `--no-track-usage` to any of those commands to leave local usage events
-unchanged.
+Successful `search`, `curate`, and `show` commands always record usage. Machine
+reads are stamped by source (below), so they never skew ranking or eval.
 
 Every runtime writer stamps provenance as `user`, `improve`, `task`, `audit`, or
 `unknown`. Direct interactive CLI traffic defaults to `user`; internal improve,

package/docs/reference/workflow-schema.md

@@ -297,13 +297,14 @@ families) plus the orchestration keys:
 - `params` — name → `{ type, description }` (JSON-Schema-typed, unlike a bare
   description string).
 - `defaults` — run-level dispatch defaults (`engine`, `model`, `llm`,
-  `timeout`, `on_error`), overridable per unit. `defaults.llm` is the
-  exception: `llm:` tuning applies only to engines of kind `llm`, and a
-  document-level `llm:` reaches EVERY step, so a document that also has a step
-  on an agent engine fails to freeze — naming the step and the engine — rather
-  than dropping the settings for that step. There is no per-step opt-out (`llm:
-  {}` is a no-op and `llm: null` is a parse error), so in a mixed document put
-  `llm:` on the `unit:` of each LLM step instead of in `defaults:`.
+  `timeout`, `on_error`), overridable per unit. `llm:` tuning reaches an engine
+  of any kind, and a document-level `llm:` reaches EVERY step. An LLM engine
+  sends it; an agent engine reports it as an `untranslated-field` notice on that
+  step (see
+  [Inference on an agent engine](configuration.md#inference-on-an-agent-engine)).
+  There is no per-step opt-out (`llm: {}` is a no-op and `llm: null` is a parse
+  error), so in a mixed document put `llm:` on the `unit:` of each step it is
+  meant for instead of in `defaults:`.
 - `outputs` — name → `{ from, schema? }`, a run-level export projected from
   a step's own artifact (Markdown-only; see [Workflow
   outputs](#workflow-outputs) below).
@@ -1179,8 +1180,8 @@ and return HTTP 500 — a hard failure, so loopback endpoints stay at 1 and a
 `engines.<name>.concurrency` yourself. Remote providers fail softly (a
 retryable 429), and four concurrent completions is well inside any hosted
 provider's entry tier. Agent engines carry no concurrency limit of their own —
-except an `opencode-sdk` engine with an `llmEngine` fallback, which inherits
-that fallback engine's limit.
+except an `opencode-sdk` engine that sets `llmEngine`, which inherits that
+fallback engine's limit.
 
 #### What counts as a loopback endpoint
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.24",
+  "version": "0.9.25-alpha.2",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [