akm-cli 0.9.22 → 0.9.24

package/CHANGELOG.md

@@ -4,6 +4,89 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.9.24] - 2026-10-02
+
+### Changed
+
+- **Reflect never auto-accepts a revision that changes the body; it waits for
+  review.** On 396 labelled reflect edits, the judge-passed edits that changed
+  the body were good 12 times in 37, and those that changed only the
+  frontmatter 13 times in 13. A revision whose body differs from the asset's,
+  ignoring whitespace, or whose source could not be read, is now created
+  pending and deferred for review with the reason `body-edit` (gate
+  `reflect`). When the quality judge passed it, the judge's scores and reason
+  stay on its gate decision. With `processes.reflect.qualityGate` off, no
+  judge ran, so the decision carries none. Before, the triage drain accepted a
+  judge-passed body edit, and its judgment tier could accept one made with the
+  gate off. These body edits now appear in the review queue
+  (`akm proposal list`), and `akm proposal show <id>` gives the reason and any
+  judge scores. A judge-passed revision that leaves the body unchanged is
+  still staged and accepted by the drain. A frontmatter-only revision made
+  with the gate off is still left to the drain, and a revision the judge fails
+  is still refused.
+
+### Fixed
+
+- **Reflect sends a revision to review when its judge fails, instead of
+  rejecting it.** A quality judge that timed out, errored or returned a reply
+  that could not be parsed gave no verdict, but reflect treated that as a
+  rejection. It created no proposal, recorded a `quality_rejected` attempt that
+  kept the asset from being reflected again for 14 days, and reported
+  `quality gate rejected: score=-1` with a reason saying the revision had been
+  routed to review. Reflect now creates the proposal and leaves it pending for
+  a person, deferred by the quality gate with the reason `judge-error`, as
+  distill does when its judge fails. The triage drain leaves it alone. It has
+  not been through the retrieval regression check, which runs only on a
+  revision the judge passes. A revision the judge scores too low is still
+  refused.
+- **The triage drain leaves every proposal a stage deferred for review to a
+  person.** It skipped a deferred proposal only when the quality gate had
+  deferred it. Reflect defers with its own gate, `reflect`: a revision whose
+  size the size guard flagged, one that echoed the truncation notice, one made
+  with no judge configured, and now a body edit. With
+  `processes.triage.judgment` enabled, the drain's judgment tier decided those
+  proposals, and under `applyMode: promote` it could accept them before anyone
+  saw them. The drain now skips every deferral it did not make itself, and
+  judges again, as before, the ones it did.
+
+## [0.9.23] - 2026-10-01
+
+### Added
+
+- **A quality gate can judge with an engine of its own (#1011).**
+  `processes.reflect.qualityGate` and `processes.distill.qualityGate` take
+  `engine`, `model`, `timeoutMs` and `llm`. These resolve over the process's own
+  settings, the way `processes.triage.judgment` resolves over triage's. Before,
+  a gate could not choose its judge. Config validation
+  rejects a gate `engine` that is missing or is not an LLM engine. A gate whose
+  settings resolve to no LLM engine fails before anything is generated, and
+  never falls back to another engine. The judge's LLM usage is recorded under
+  its own engine, so the improve report shows it on its own row.
+
+### Changed
+
+- **A judge whose engine sets `enableThinking: true` now thinks.** The reflect
+  and distill judges always turned thinking off. They still do, unless the
+  judge's engine turns it on, so a thinking judge can be configured. To keep a
+  thinking engine's judge from thinking, set
+  `qualityGate.llm.enableThinking: false`. In the maintainer's replay of
+  labelled reflect edits, a thinking judge passed more of the good edits, and
+  more of the bad ones too. It used about 20 times the tokens and took a median
+  of 30–67 s per judgment, against about 5 s, so it stays opt-in.
+
+### Fixed
+
+- **The reflect quality gate follows its own switch.** It ran when either
+  `processes.reflect.qualityGate.enabled` was true or distill's gate was on,
+  which it is by default. So `reflect.qualityGate.enabled: false` did nothing
+  unless distill's gate was off too, and turning distill's gate off also turned
+  off reflect's. Each gate now follows only its own `enabled`, which defaults to
+  on.
+- **Memory inference uses the configured temperature.** It always sent 0.1,
+  ignoring the engine's `temperature` and
+  `processes.memoryInference.llm.temperature`. It now sends the configured
+  temperature, and 0.1 only when nothing sets one.
+
 ## [0.9.22] - 2026-10-01
 
 ### Fixed

package/dist/commands/improve/distill.js

@@ -46,7 +46,7 @@ import { buildRefVocabulary, scoreEncodingSalience } from "./encoding-salience.j
 import { resolveImproveStrategy, resolveProcessEnabled } from "./improve-strategies.js";
 import { recordLedgerAttempt } from "./ledger.js";
 import { computeSalience, upsertAssetSalience } from "./salience.js";
-import { callStage, mintProposal, noticeSet, rejectedProposalContext, runLessonQualityJudge, stageRunner, } from "./stage.js";
+import { callStage, mintProposal, noticeSet, rejectedProposalContext, resolveQualityGateJudge, runLessonQualityJudge, stageRunner, } from "./stage.js";
 /**
  * Input types distill structurally refuses: a lesson is the distilled form
  * (distilling one would mint `lessons/lesson-…-lesson`), and env/secret bytes
@@ -306,6 +306,7 @@ export async function akmDistill(options) {
         config,
         profile,
         runner: stageRunner(options, config, profile, "distill", notices.add),
+        judgeRunner: resolveQualityGateJudge(config, profile, "distill", notices.add),
         notices,
         eligMeta,
         asset,
@@ -322,8 +323,11 @@ async function distill(run, targetKind, kind, outputRef, feedbackEvents) {
     // A reinforced memory graduates to knowledge without a generation call.
     const promotion = targetKind === "lesson" ? null : await planPromotion(run, feedbackEvents);
     if (promotion) {
-        if (run.runner && (promotion.existing || qualityGateEnabled(run)))
+        if (run.runner && promotion.existing)
             assertRunnerCredentials(run.runner);
+        const judge = run.judgeRunner ?? run.runner;
+        if (judge && qualityGateEnabled(run))
+            assertRunnerCredentials(judge);
         const promoted = await promoteToKnowledge(run, promotion);
         stampInputSalience(run);
         return promoted;
@@ -441,7 +445,7 @@ async function judgeAndQueue(run, out) {
         const source = out.source ? parseFrontmatter(out.source).content.trim() : "";
         const verdict = await runLessonQualityJudge(run.config, content, source, run.options.chat, {
             ...(similarLessons.length > 0 ? { similarLessons } : {}),
-            ...(run.runner ? { llmRunner: run.runner } : {}),
+            ...((run.judgeRunner ?? run.runner) ? { llmRunner: run.judgeRunner ?? run.runner } : {}),
             ...(run.options.signal ? { signal: run.options.signal } : {}),
             onNotices: run.notices.add,
         });

package/dist/commands/improve/reflect.js

@@ -44,7 +44,7 @@ import { resolveImproveLlmExecution } from "./execution.js";
 import { recordLedgerAttempt } from "./ledger.js";
 import { classifyReflectChange, splitFrontmatter } from "./reflect-noise.js";
 import { loadRetrievalQueries, runRetrievalRegressionGate } from "./retrieval-gate.js";
-import { callStage, mintProposal, noticeSet, rejectedProposalContext, runReflectQualityJudge, } from "./stage.js";
+import { callStage, mintProposal, noticeSet, rejectedProposalContext, resolveQualityGateJudge, runReflectQualityJudge, } from "./stage.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
 function readOnlyEventsContext(ctx) {
@@ -932,8 +932,10 @@ const NOISE_SUBREASONS = {
 };
 /**
  * Sanitize, drop a no-op/cosmetic (and optionally low-value) change, judge the
- * exact content that would be persisted, then mint. Size-flagged or
- * truncation-leaking content skips the judge and waits for review.
+ * exact content that would be persisted, then mint. A judge pass is staged only
+ * when the body is unchanged: a body edit the judge passes, or one made with the
+ * gate off, waits for review. Size-flagged or truncation-leaking content skips
+ * the judge and waits for review.
  */
 async function finalizeReflectProposal(args) {
     const { run, assetContent, result, judge, feedback } = args;
@@ -980,6 +982,7 @@ async function finalizeReflectProposal(args) {
         return reflectFailure(run, result, "quality_rejected", message, false);
     };
     let verdict;
+    let judgeFailed = false;
     if (judged) {
         verdict = await runReflectQualityJudge(run.config, payload.content, assetContent ?? "", feedback, options.chat, {
             runnerSelectionFrozen: true,
@@ -988,7 +991,9 @@ async function finalizeReflectProposal(args) {
             ...(options.signal ? { signal: options.signal } : {}),
             onNotices: run.notices.add,
         });
-        if (!verdict.pass) {
+        // A judge that timed out, errored or replied unparseably gave no verdict: a person reviews the revision.
+        judgeFailed = verdict.reviewNeeded === true && verdict.score === -1;
+        if (!verdict.pass && !judgeFailed) {
             return refuse(verdict.reason, {
                 qualityScore: verdict.score,
                 qualityReason: verdict.reason,
@@ -997,7 +1002,7 @@ async function finalizeReflectProposal(args) {
         }
     }
     // #722: a rewrite of an existing asset must not grade lower on its own retrieval queries.
-    if (judged && judge.runner && assetContent !== undefined) {
+    if (verdict?.pass && judge.runner && assetContent !== undefined) {
         const retrieval = await runRetrievalRegressionGate({
             ref: payload.ref,
             before: assetContent,
@@ -1026,9 +1031,18 @@ async function finalizeReflectProposal(args) {
     };
     const reviewReasons = [
         ...(judge.skippedNoJudge ? ["no-judge-configured"] : []),
+        ...(judgeFailed ? ["judge-error"] : []),
         ...(sanitized.sizeGuardRatio ? ["reflect-size-ratio"] : []),
         ...(sanitized.truncationMarkerLeaked ? ["reflect-truncation-leak"] : []),
     ];
+    // A revision that changes the body is never auto-accepted: on labelled edits, the judge's
+    // passes on body edits were good 12 times in 37, and on frontmatter-only edits 13 in 13.
+    // One that nothing above holds for review (the judge passed it, or the gate is off) waits
+    // for a person, as does a revision with no source to compare.
+    const bodyOf = (content) => splitFrontmatter(content).body.replace(/\s+/g, " ").trim();
+    const bodyEdit = reviewReasons.length === 0 && (assetContent === undefined || bodyOf(assetContent) !== bodyOf(payload.content));
+    if (bodyEdit)
+        reviewReasons.push("body-edit");
     const proposal = mintProposal(run.stash, options.ctx, {
         ref: payload.ref,
         ...(options.target ? { target: options.target } : {}),
@@ -1042,8 +1056,12 @@ async function finalizeReflectProposal(args) {
         ? {
             review: {
                 reason: reviewReasons.join("+"),
-                gate: "reflect",
+                // The quality gate's hand-off to a person, as distill's: the triage drain leaves it alone.
+                gate: judgeFailed ? "quality-gate" : "reflect",
                 ...(sanitized.sizeGuardRatio ? { measured: Math.round(sanitized.sizeGuardRatio.ratio * 100) } : {}),
+                // The reviewer sees why the judge passed it (with the gate off, nothing judged it).
+                ...(bodyEdit && verdict?.criteria ? { scores: verdict.criteria } : {}),
+                ...(bodyEdit && verdict ? { judgeReason: verdict.reason } : {}),
             },
         }
         : { judged: verdict });
@@ -1055,6 +1073,7 @@ async function finalizeReflectProposal(args) {
             source: "reflect",
             engine: run.engineName,
             ...(judge.skippedNoJudge ? { qualityGateSkippedNoJudge: true } : {}),
+            ...(judgeFailed ? { qualityReason: verdict?.reason } : {}),
             ...(sanitized.sizeGuardRatio
                 ? { sizeGuardRatio: sanitized.sizeGuardRatio.code, sizeGuardRatioValue: sanitized.sizeGuardRatio.ratio }
                 : {}),
@@ -1113,11 +1132,14 @@ export async function akmReflect(options = {}) {
     notices.add(resolutionNotices);
     const run = { options, stash, config, runnerSpec, engineName, notices, emitInvoked, emitFailed };
     // Judge selection is frozen before dispatch so a missing judge credential fails first.
-    const judgeWanted = (activeStrategy?.processes?.reflect?.qualityGate?.enabled ?? false) ||
-        (activeStrategy?.processes?.distill?.qualityGate?.enabled ?? true);
+    const judgeWanted = activeStrategy?.processes?.reflect?.qualityGate?.enabled ?? true;
     let judgeRunner;
     if (judgeWanted) {
-        if (runnerIsLlm(runnerSpec)) {
+        const gateJudge = resolveQualityGateJudge(config, activeStrategy, "reflect", notices.add);
+        if (gateJudge) {
+            judgeRunner = gateJudge;
+        }
+        else if (runnerIsLlm(runnerSpec)) {
             judgeRunner = runnerSpec;
         }
         else {

package/dist/commands/improve/stage.js

@@ -7,7 +7,7 @@ import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { warn } from "../../core/warn.js";
 import { LlmCallError } from "../../llm/client.js";
 import { callStructured } from "../../llm/structured-call.js";
-import { withLlmStage } from "../../llm/usage-telemetry.js";
+import { currentLlmStage, withLlmStage } from "../../llm/usage-telemetry.js";
 import { isProceduralRejection } from "../proposal/proposal-types.js";
 import { createProposal, listProposalsReadOnly, proposalContentHash, recordGateDecision, } from "../proposal/repository.js";
 import { resolveImproveLlmExecution } from "./execution.js";
@@ -55,7 +55,7 @@ export async function callStage(call) {
     ];
     let failure;
     try {
-        const raw = await callStructured({
+        const dispatch = () => callStructured({
             feature: call.feature,
             ...(call.gate
                 ? { akmConfig: call.gate.config, ...(call.gate.enabled !== undefined ? { enabled: call.gate.enabled } : {}) }
@@ -74,6 +74,12 @@ export async function callStage(call) {
                 failure ??= { ok: false, reason: event.reason, ...(event.error ? { error: event.error.message } : {}) };
             },
         });
+        // Usage is credited to the engine that serves the call, which for a gate's own judge
+        // (#1011) is not the stage's planned engine.
+        const stage = currentLlmStage();
+        const raw = await (stage === undefined
+            ? dispatch()
+            : withLlmStage(stage, dispatch, { engine: call.runner.engine }));
         return raw === undefined ? (failure ?? { ok: false, reason: "error" }) : { ok: true, raw };
     }
     catch (err) {
@@ -152,6 +158,34 @@ export function stageJudgedProposal(stash, proposal, judged, proposalsCtx) {
         return proposal;
     }
 }
+/**
+ * The judge a quality gate names for itself (#1011): the gate's `engine`,
+ * `model`, `timeoutMs` and `llm` over the process's own settings, as
+ * `processes.triage.judgment` resolves over triage. `undefined` when the gate
+ * is off or sets none of them, so the caller keeps its own judge. Throws when
+ * they resolve to no LLM engine, before anything is generated: a judge must be
+ * one, and the gate never falls back to another.
+ */
+export function resolveQualityGateJudge(config, profile, processName, onNotices) {
+    const process = profile?.processes?.[processName];
+    const gate = process?.qualityGate;
+    if (!gate || gate.enabled === false)
+        return undefined;
+    if (!["engine", "model", "timeoutMs", "llm"].some((key) => Object.hasOwn(gate, key)))
+        return undefined;
+    const resolved = resolveImproveLlmExecution({
+        config,
+        processName: `${processName}-quality-judge`,
+        ...(profile ? { profile } : {}),
+        ...(process ? { process } : {}),
+        current: gate,
+    });
+    if (!resolved) {
+        throw new ConfigError(`The ${processName} quality gate's judge must be an LLM engine. Set processes.${processName}.qualityGate.engine to one.`, "INVALID_CONFIG_FILE");
+    }
+    onNotices?.(resolved.notices);
+    return resolved.runner;
+}
 /** Lesson judge prompt; similar existing lessons let it mark near-duplicates down. */
 export function buildJudgePrompt(lessonContent, sourceContent, similarLessons) {
     const lines = [
@@ -328,7 +362,8 @@ async function runQualityJudge(feature, config, prompt, keys, chat, options) {
         system: "Return only valid JSON. No prose.",
         prompt,
         request: {
-            enableThinking: false,
+            // Off unless the judge's own engine enables thinking (a slower, separate judge engine, #1011).
+            enableThinking: runner.connection.enableThinking === true,
             temperature: 0,
             responseSchema: judgeResponseSchema(keys),
             ...(Object.hasOwn(options, "timeoutMs") ? { timeoutMs: options.timeoutMs } : {}),

package/dist/commands/proposal/drain.js

@@ -13,8 +13,8 @@
  *     is configured, and whatever stays undecided is left for review
  *     (`review_needed` in the improve ledger).
  * `maxAccepts` caps promotions across both tiers; `applyMode: "queue"` never
- * promotes; `excludeIds` keeps this run's fresh proposals out; a proposal the
- * distill quality gate routed to a human is left for that human.
+ * promotes; `excludeIds` keeps this run's fresh proposals out; a proposal that
+ * a generating stage routed to a person is left for that person.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -313,11 +313,11 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
         if (isRetireProposal(proposal))
             continue;
         const decision = proposal.gateDecision;
-        // Another gate's rejection stands; a human-review deferral from the distill
-        // quality gate is left for that human.
+        // Another gate's rejection stands, and another gate's deferral is a
+        // generating stage's hand-off to a person: it is left for that person.
         if (decision?.outcome === "auto-rejected" && !decision.gate?.startsWith(DRAIN_GATE))
             continue;
-        if (decision?.outcome === "deferred" && decision.gate === "quality-gate")
+        if (decision?.outcome === "deferred" && !decision.gate?.startsWith(DRAIN_GATE))
             continue;
         if (isEmptyDiff(proposal)) {
             empties.push(proposal.id);

package/dist/core/config/config-schema.js

@@ -308,6 +308,16 @@ export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) =>
                     });
                 }
             }
+            const gateEngine = processConfig.qualityGate?.engine;
+            if (gateEngine && config.engines?.[gateEngine]?.kind !== "llm") {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["improve", "strategies", strategyName, "processes", processName, "qualityGate", "engine"],
+                    message: config.engines?.[gateEngine]
+                        ? "a quality-gate judge must be an LLM engine"
+                        : "engine does not name a configured engine",
+                });
+            }
         }
     }
     // #464.a: defaultWriteTarget must name a configured source. 0.9.0 (spec

package/dist/core/config/schema/improve-processes.js

@@ -59,12 +59,23 @@ const excludeRefPrefixesField = z.array(z.string().min(1)).optional();
  */
 const processLimitField = positiveInt.optional();
 /**
- * Distill process: LLM-as-judge lesson quality gate. Default ON (R3);
- * fail-open — judge failure/timeout/parse errors pass through. Set
- * `enabled: false` on the distill process to opt out. Also read on the
- * `reflect` process (proposal-side quality gate; see reflect.ts).
+ * The distill and reflect LLM-as-judge quality gates. Default ON; set
+ * `enabled: false` on the process to opt out. A judge error, timeout or
+ * unparsable reply never passes: distill sends the lesson to review and
+ * reflect refuses the edit. `engine`, `model`, `timeoutMs` and `llm` give the
+ * gate a judge of its own (#1011), resolved over the process's own settings;
+ * with none set, the gate judges with the generator's runner.
  */
-const qualityGateField = z.object({ enabled: z.boolean().optional() }).passthrough().optional();
+const qualityGateField = z
+    .object({
+    enabled: z.boolean().optional(),
+    engine: engineName.optional(),
+    model: nonEmptyString.optional(),
+    timeoutMs: z.union([positiveInt, z.null()]).optional(),
+    llm: LlmInvocationOverridesSchema.passthrough().optional(),
+})
+    .passthrough()
+    .optional();
 /**
  * WS-3b: CLS (Complementary Learning System) interleaving (step 9).
  * distill/memoryInference prompts include embedding-retrieved existing adjacent

package/dist/llm/memory-infer.js

@@ -88,7 +88,8 @@ export async function compressMemoryToDerivedMemory(llmRunner, body, signal, akm
             { role: "user", content: userPrompt },
         ],
         request: {
-            temperature: 0.1,
+            // The engine's or the process's configured temperature; 0.1 only when neither sets one.
+            temperature: llmRunner.connection.temperature ?? 0.1,
             timeoutMs: llmRunner.timeoutMs,
             signal,
             responseSchema: DERIVED_MEMORY_JSON_SCHEMA,

package/dist/scripts/akm-migrate-node.js

@@ -35851,7 +35851,13 @@ var IMPROVE_PROCESS_BASE_FIELDS = {
 var allowedTypesField = exports_external.array(exports_external.string().min(1)).optional();
 var excludeRefPrefixesField = exports_external.array(exports_external.string().min(1)).optional();
 var processLimitField = positiveInt.optional();
-var qualityGateField = exports_external.object({ enabled: exports_external.boolean().optional() }).passthrough().optional();
+var qualityGateField = exports_external.object({
+  enabled: exports_external.boolean().optional(),
+  engine: engineName.optional(),
+  model: nonEmptyString.optional(),
+  timeoutMs: exports_external.union([positiveInt, exports_external.null()]).optional(),
+  llm: LlmInvocationOverridesSchema.passthrough().optional()
+}).passthrough().optional();
 var clsField = exports_external.object({
   enabled: exports_external.boolean().optional(),
   adjacentCount: exports_external.number().int().min(1).optional()
@@ -36468,6 +36474,14 @@ var AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) => {
           });
         }
       }
+      const gateEngine = processConfig.qualityGate?.engine;
+      if (gateEngine && config.engines?.[gateEngine]?.kind !== "llm") {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          path: ["improve", "strategies", strategyName, "processes", processName, "qualityGate", "engine"],
+          message: config.engines?.[gateEngine] ? "a quality-gate judge must be an LLM engine" : "engine does not name a configured engine"
+        });
+      }
     }
   }
   if (config.defaultWriteTarget !== undefined) {

package/dist/scripts/akm-migrate.js

@@ -35179,7 +35179,13 @@ var IMPROVE_PROCESS_BASE_FIELDS = {
 var allowedTypesField = exports_external.array(exports_external.string().min(1)).optional();
 var excludeRefPrefixesField = exports_external.array(exports_external.string().min(1)).optional();
 var processLimitField = positiveInt.optional();
-var qualityGateField = exports_external.object({ enabled: exports_external.boolean().optional() }).passthrough().optional();
+var qualityGateField = exports_external.object({
+  enabled: exports_external.boolean().optional(),
+  engine: engineName.optional(),
+  model: nonEmptyString.optional(),
+  timeoutMs: exports_external.union([positiveInt, exports_external.null()]).optional(),
+  llm: LlmInvocationOverridesSchema.passthrough().optional()
+}).passthrough().optional();
 var clsField = exports_external.object({
   enabled: exports_external.boolean().optional(),
   adjacentCount: exports_external.number().int().min(1).optional()
@@ -35796,6 +35802,14 @@ var AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) => {
           });
         }
       }
+      const gateEngine = processConfig.qualityGate?.engine;
+      if (gateEngine && config.engines?.[gateEngine]?.kind !== "llm") {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          path: ["improve", "strategies", strategyName, "processes", processName, "qualityGate", "engine"],
+          message: config.engines?.[gateEngine] ? "a quality-gate judge must be an LLM engine" : "engine does not name a configured engine"
+        });
+      }
     }
   }
   if (config.defaultWriteTarget !== undefined) {

package/docs/reference/cli.md

@@ -3039,9 +3039,11 @@ Drain the standing pending-proposal backlog instead of adjudicating proposals
 one at a time. One rule decides each proposal: a proposal whose quality judge
 passed on its current content is accepted (unless its target changed since it
 was minted — that one is auto-rejected as `stale-target`); an empty diff is
-rejected; everything else goes to the judgment tier when one is enabled, and
-is otherwise left for review. Default mode stages decisions (queue mode); pass
-`--promote` to actually accept.
+rejected; a proposal that reflect or distill deferred for review is left for a
+person; everything else goes to the judgment tier when one is enabled, and
+is otherwise left for review. A reflect revision that changes the body is
+deferred for review even when its judge passes it. Default mode stages
+decisions (queue mode); pass `--promote` to actually accept.
 
 ```sh
 akm proposal drain --dry-run                        # Preview without writing

package/docs/reference/configuration.md

@@ -103,10 +103,11 @@ An LLM engine may set `enableThinking: false` to turn thinking off and
 `reasoningEffort` to a value such as `"none"`, `"low"`, or `"high"`. AKM sends
 **both** wire forms — `chat_template_kwargs.enable_thinking` and top-level
 `enable_thinking` — whenever `enableThinking` resolves, from engine config
-or a calling process (improve's `consolidate`/`reflect` and the distill
-quality gate always request `enableThinking: false` for a machine-readable
-payload); `reasoningEffort` is always sent as top-level `reasoning_effort`
-when set. Backend support: llama.cpp direct honors both forms
+or a calling process (improve's `consolidate`/`reflect` always request
+`enableThinking: false` for a machine-readable payload, and the reflect and
+distill quality-gate judges do too unless the judge's engine sets
+`enableThinking: true`); `reasoningEffort` is always sent as top-level
+`reasoning_effort` when set. Backend support: llama.cpp direct honors both forms
 (`reasoning_effort` from build ≥ b10644); vLLM honors
 `chat_template_kwargs`; Bifrost drops `chat_template_kwargs` and passes
 `reasoning_effort` through, so also set `reasoningEffort: "none"` behind it; a
@@ -353,6 +354,44 @@ guidance. When enabled, engine selection is judgment → triage → strategy →
 }
 ```
 
+`processes.reflect.qualityGate` and `processes.distill.qualityGate` control
+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,
+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
+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.
+Behind a gateway that drops `chat_template_kwargs` (Bifrost), point a thinking
+judge's engine at the server directly.
+
+```jsonc
+{
+  "engines": {
+    "judge": {
+      "kind": "llm",
+      "endpoint": "http://127.0.0.1:8080/v1/chat/completions",
+      "model": "qwen3-27b",
+      "enableThinking": true
+    }
+  },
+  "improve": {
+    "strategies": {
+      "nightly": {
+        "processes": {
+          "reflect": { "qualityGate": { "engine": "judge" } }
+        }
+      }
+    }
+  }
+}
+```
+
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.22",
+  "version": "0.9.24",
   "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": [

package/schemas/akm-config.json

@@ -756,6 +756,57 @@
                         "properties": {
                           "enabled": {
                             "type": "boolean"
+                          },
+                          "engine": {
+                            "type": "string",
+                            "maxLength": 63,
+                            "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+                          },
+                          "model": {
+                            "type": "string",
+                            "minLength": 1
+                          },
+                          "timeoutMs": {
+                            "anyOf": [
+                              {
+                                "type": "integer",
+                                "exclusiveMinimum": 0
+                              },
+                              {
+                                "type": "null"
+                              }
+                            ]
+                          },
+                          "llm": {
+                            "type": "object",
+                            "properties": {
+                              "temperature": {
+                                "type": "number"
+                              },
+                              "maxTokens": {
+                                "type": "integer",
+                                "exclusiveMinimum": 0
+                              },
+                              "supportsJsonSchema": {
+                                "type": "boolean"
+                              },
+                              "extraParams": {
+                                "type": "object",
+                                "additionalProperties": {}
+                              },
+                              "contextLength": {
+                                "type": "integer",
+                                "exclusiveMinimum": 0
+                              },
+                              "enableThinking": {
+                                "type": "boolean"
+                              },
+                              "reasoningEffort": {
+                                "type": "string",
+                                "minLength": 1
+                              }
+                            },
+                            "additionalProperties": true
                           }
                         },
                         "additionalProperties": true
@@ -845,6 +896,57 @@
                         "properties": {
                           "enabled": {
                             "type": "boolean"
+                          },
+                          "engine": {
+                            "type": "string",
+                            "maxLength": 63,
+                            "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+                          },
+                          "model": {
+                            "type": "string",
+                            "minLength": 1
+                          },
+                          "timeoutMs": {
+                            "anyOf": [
+                              {
+                                "type": "integer",
+                                "exclusiveMinimum": 0
+                              },
+                              {
+                                "type": "null"
+                              }
+                            ]
+                          },
+                          "llm": {
+                            "type": "object",
+                            "properties": {
+                              "temperature": {
+                                "type": "number"
+                              },
+                              "maxTokens": {
+                                "type": "integer",
+                                "exclusiveMinimum": 0
+                              },
+                              "supportsJsonSchema": {
+                                "type": "boolean"
+                              },
+                              "extraParams": {
+                                "type": "object",
+                                "additionalProperties": {}
+                              },
+                              "contextLength": {
+                                "type": "integer",
+                                "exclusiveMinimum": 0
+                              },
+                              "enableThinking": {
+                                "type": "boolean"
+                              },
+                              "reasoningEffort": {
+                                "type": "string",
+                                "minLength": 1
+                              }
+                            },
+                            "additionalProperties": true
                           }
                         },
                         "additionalProperties": true
@@ -2306,6 +2408,57 @@
                             "properties": {
                               "enabled": {
                                 "type": "boolean"
+                              },
+                              "engine": {
+                                "type": "string",
+                                "maxLength": 63,
+                                "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+                              },
+                              "model": {
+                                "type": "string",
+                                "minLength": 1
+                              },
+                              "timeoutMs": {
+                                "anyOf": [
+                                  {
+                                    "type": "integer",
+                                    "exclusiveMinimum": 0
+                                  },
+                                  {
+                                    "type": "null"
+                                  }
+                                ]
+                              },
+                              "llm": {
+                                "type": "object",
+                                "properties": {
+                                  "temperature": {
+                                    "type": "number"
+                                  },
+                                  "maxTokens": {
+                                    "type": "integer",
+                                    "exclusiveMinimum": 0
+                                  },
+                                  "supportsJsonSchema": {
+                                    "type": "boolean"
+                                  },
+                                  "extraParams": {
+                                    "type": "object",
+                                    "additionalProperties": {}
+                                  },
+                                  "contextLength": {
+                                    "type": "integer",
+                                    "exclusiveMinimum": 0
+                                  },
+                                  "enableThinking": {
+                                    "type": "boolean"
+                                  },
+                                  "reasoningEffort": {
+                                    "type": "string",
+                                    "minLength": 1
+                                  }
+                                },
+                                "additionalProperties": true
                               }
                             },
                             "additionalProperties": true
@@ -2395,6 +2548,57 @@
                             "properties": {
                               "enabled": {
                                 "type": "boolean"
+                              },
+                              "engine": {
+                                "type": "string",
+                                "maxLength": 63,
+                                "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+                              },
+                              "model": {
+                                "type": "string",
+                                "minLength": 1
+                              },
+                              "timeoutMs": {
+                                "anyOf": [
+                                  {
+                                    "type": "integer",
+                                    "exclusiveMinimum": 0
+                                  },
+                                  {
+                                    "type": "null"
+                                  }
+                                ]
+                              },
+                              "llm": {
+                                "type": "object",
+                                "properties": {
+                                  "temperature": {
+                                    "type": "number"
+                                  },
+                                  "maxTokens": {
+                                    "type": "integer",
+                                    "exclusiveMinimum": 0
+                                  },
+                                  "supportsJsonSchema": {
+                                    "type": "boolean"
+                                  },
+                                  "extraParams": {
+                                    "type": "object",
+                                    "additionalProperties": {}
+                                  },
+                                  "contextLength": {
+                                    "type": "integer",
+                                    "exclusiveMinimum": 0
+                                  },
+                                  "enableThinking": {
+                                    "type": "boolean"
+                                  },
+                                  "reasoningEffort": {
+                                    "type": "string",
+                                    "minLength": 1
+                                  }
+                                },
+                                "additionalProperties": true
                               }
                             },
                             "additionalProperties": true
@@ -3316,6 +3520,57 @@
           "properties": {
             "enabled": {
               "type": "boolean"
+            },
+            "engine": {
+              "type": "string",
+              "maxLength": 63,
+              "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+            },
+            "model": {
+              "type": "string",
+              "minLength": 1
+            },
+            "timeoutMs": {
+              "anyOf": [
+                {
+                  "type": "integer",
+                  "exclusiveMinimum": 0
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "llm": {
+              "type": "object",
+              "properties": {
+                "temperature": {
+                  "type": "number"
+                },
+                "maxTokens": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0
+                },
+                "supportsJsonSchema": {
+                  "type": "boolean"
+                },
+                "extraParams": {
+                  "type": "object",
+                  "additionalProperties": {}
+                },
+                "contextLength": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0
+                },
+                "enableThinking": {
+                  "type": "boolean"
+                },
+                "reasoningEffort": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "additionalProperties": true
             }
           },
           "additionalProperties": true
@@ -3655,6 +3910,57 @@
                   "properties": {
                     "enabled": {
                       "type": "boolean"
+                    },
+                    "engine": {
+                      "type": "string",
+                      "maxLength": 63,
+                      "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+                    },
+                    "model": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "timeoutMs": {
+                      "anyOf": [
+                        {
+                          "type": "integer",
+                          "exclusiveMinimum": 0
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "llm": {
+                      "type": "object",
+                      "properties": {
+                        "temperature": {
+                          "type": "number"
+                        },
+                        "maxTokens": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0
+                        },
+                        "supportsJsonSchema": {
+                          "type": "boolean"
+                        },
+                        "extraParams": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        },
+                        "contextLength": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0
+                        },
+                        "enableThinking": {
+                          "type": "boolean"
+                        },
+                        "reasoningEffort": {
+                          "type": "string",
+                          "minLength": 1
+                        }
+                      },
+                      "additionalProperties": true
                     }
                   },
                   "additionalProperties": true
@@ -3744,6 +4050,57 @@
                   "properties": {
                     "enabled": {
                       "type": "boolean"
+                    },
+                    "engine": {
+                      "type": "string",
+                      "maxLength": 63,
+                      "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+                    },
+                    "model": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "timeoutMs": {
+                      "anyOf": [
+                        {
+                          "type": "integer",
+                          "exclusiveMinimum": 0
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "llm": {
+                      "type": "object",
+                      "properties": {
+                        "temperature": {
+                          "type": "number"
+                        },
+                        "maxTokens": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0
+                        },
+                        "supportsJsonSchema": {
+                          "type": "boolean"
+                        },
+                        "extraParams": {
+                          "type": "object",
+                          "additionalProperties": {}
+                        },
+                        "contextLength": {
+                          "type": "integer",
+                          "exclusiveMinimum": 0
+                        },
+                        "enableThinking": {
+                          "type": "boolean"
+                        },
+                        "reasoningEffort": {
+                          "type": "string",
+                          "minLength": 1
+                        }
+                      },
+                      "additionalProperties": true
                     }
                   },
                   "additionalProperties": true