akm-cli 0.9.23 → 0.9.24

package/CHANGELOG.md

@@ -4,6 +4,51 @@ 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

package/dist/commands/improve/reflect.js

@@ -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 }
                 : {}),

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/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

@@ -356,7 +356,9 @@ 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. The judge is the
+`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

package/package.json

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