akm-cli 0.9.16 → 0.9.17-alpha.2

package/dist/commands/improve/preparation.js

@@ -22,7 +22,7 @@ import { listStateProposals } from "../../storage/repositories/proposals-reposit
 import { akmLint } from "../lint/index.js";
 import { runSchemaRepairPass } from "../sources/schema-repair.js";
 import { isAutonomyLaneAllowed } from "./autonomy-gate.js";
-import { akmConsolidate, inspectConsolidationPool } from "./consolidate.js";
+import { akmConsolidate, inspectConsolidationPool, loadExistingKnowledgeBodyHashes } from "./consolidate.js";
 import { computeSafeChunkSize, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
 // Eligibility / candidate-selection predicates live in ./eligibility.
 import { buildLatestFeedbackTsMap, buildLatestProposalTsMap, buildUtilityMap, dedupeRefs, findAssetFilePath, isDistillCandidateRef, isLessonCandidate, isSignalDeltaEligible, resolveImproveScope, } from "./eligibility.js";
@@ -133,11 +133,15 @@ function evaluateConsolidationEligibility(args) {
     // Bootstrap: when no successful consolidate_completed event has ever been
     // recorded, we cannot evaluate the pool-delta — treat as eligible so a
     // fresh stash runs consolidate once before the steady-state gate kicks in.
+    //
+    // R4: the volume override is bootstrap-only — it exists to force that same
+    // "fresh stash, consolidate once" run when the pool is already large enough
+    // that waiting for the steady-state gate would be wasteful. Once a
+    // consolidate_completed event exists, the pool-delta gate below governs on
+    // its own; a large eligible pool no longer bypasses it.
     const memoryUpdatedAfterLastConsolidate = (() => {
-        if (volumeTriggered)
-            return true; // volume override forces the run regardless.
         if (!lastConsolidateTs)
-            return true; // bootstrap path: never consolidated.
+            return true; // bootstrap path: never consolidated (volume override included).
         if (!primaryStashDir)
             return false;
         const memoriesDir = path.join(primaryStashDir, "memories");
@@ -172,7 +176,10 @@ function evaluateConsolidationEligibility(args) {
             return false;
         }
     })();
-    const consolidationOnCooldown = !volumeTriggered && !memoryUpdatedAfterLastConsolidate;
+    // R4: no longer `!volumeTriggered && ...` — the volume override only ever
+    // applies at bootstrap (see `memoryUpdatedAfterLastConsolidate` above), so
+    // the pool-delta result alone determines cooldown post-bootstrap.
+    const consolidationOnCooldown = !memoryUpdatedAfterLastConsolidate;
     // Profile gate: if profile explicitly disables consolidate, skip the entire pass.
     const consolidateDisabledByProfile = improveProfile?.processes?.consolidate?.enabled === false;
     // #553 minPoolSize guard: skip consolidation when the eligible memory pool is
@@ -225,11 +232,13 @@ function planConsolidationPass(args) {
         maxChunkSize: processConfig?.maxChunkSize,
     };
     const poolWarnings = [];
+    // Same hash set the live run's pre-filter uses (R2-1), so the preview's
+    // candidate pool and eligibility gate agree with what the run will act on.
+    // Reuse the caller's set when given one (runConsolidationPass) instead of
+    // walking knowledge/ again here.
     const pool = primaryStashDir
-        ? inspectConsolidationPool(effectiveOptions, primaryStashDir, poolWarnings, {
-            readOnly: eventsCtx?.readOnly === true,
-        })
-        : { poolSize: 0, candidatePoolSize: 0, dedupPoolSize: 0, memories: [] };
+        ? inspectConsolidationPool(effectiveOptions, primaryStashDir, poolWarnings, args.existingKnowledgeBodyHashes ?? loadExistingKnowledgeBodyHashes(primaryStashDir), { readOnly: eventsCtx?.readOnly === true })
+        : { poolSize: 0, candidatePoolSize: 0, dedupPoolSize: 0, memories: [], prefilteredAlreadyPromoted: 0 };
     // #800/#957 round 3 — a credential-unavailable consolidate engine still
     // resolved a context length structurally; read it off the `engineUnavailable`
     // entry instead of falling back to the generic default, so a dry-run
@@ -284,7 +293,11 @@ function planConsolidationPass(args) {
                 },
                 delta: {
                     passed: deltaPassed,
-                    reason: deltaPassed ? "memory pool has work" : "no updates since the last completed consolidation",
+                    reason: !deltaPassed
+                        ? "no updates since the last completed consolidation"
+                        : eligibility.lastConsolidationTs
+                            ? "memory pool has work"
+                            : "no completed consolidation recorded yet (bootstrap)",
                 },
             },
             wouldRun,
@@ -297,6 +310,10 @@ export async function runConsolidationPass(args) {
     const { options, primaryStashDir, memorySummary, improveProfile, resolvedPlan, eventsCtx, budgetSignal, runBudgetMs, } = args;
     const baseConfig = options.config ?? loadConfig();
     const consolidationConfig = baseConfig;
+    // Computed once here and reused by both the pool preview below and the
+    // akmConsolidate call further down (R2-1/R3-1) — knowledge/ can hold
+    // thousands of files, so walking it twice per run would double that cost.
+    const existingKnowledgeBodyHashes = primaryStashDir ? loadExistingKnowledgeBodyHashes(primaryStashDir) : undefined;
     const planned = planConsolidationPass({
         options,
         primaryStashDir,
@@ -304,6 +321,7 @@ export async function runConsolidationPass(args) {
         improveProfile,
         resolvedPlan,
         eventsCtx,
+        existingKnowledgeBodyHashes,
     });
     const { volumeTriggered, consolidationOnCooldown, consolidateDisabledByProfile, poolBelowMinSize, eligiblePoolSize, minPoolSize, lastConsolidationTs, } = planned.eligibility;
     let consolidation = {
@@ -351,6 +369,9 @@ export async function runConsolidationPass(args) {
             improveProfile,
             llmRunner: resolvedPlan.processes.consolidate.runner,
             autoTriggered: volumeTriggered,
+            // Reuse the hash set computed above instead of a second knowledge/
+            // walk inside akmConsolidateInner (R2-1/R3-1).
+            existingKnowledgeBodyHashes,
             // Tie consolidate proposals back to this improve invocation so
             // accept-rate-per-run aggregation works. Mirrors reflect/propose/extract.
             sourceRun: `consolidate-${Date.now()}`,
@@ -375,12 +396,14 @@ export async function runConsolidationPass(args) {
             (consolidation.failedChunkMemories ?? 0) === 0 &&
             (consolidation.failedPromotions ?? 0) === 0 &&
             (consolidation.deferredMemories ?? 0) === 0;
-        const hasUnappliedAdvisoryOperations = consolidation.planned?.some((op) => op.op !== "promote") ?? false;
-        if (consolidation.ok &&
-            !consolidation.dryRun &&
-            complete &&
-            !hasUnappliedAdvisoryOperations &&
-            consolidation.processed > 0) {
+        // R4: advisory ops (merge/delete/contradict) are never auto-applied — see
+        // consolidate.ts — so a run that plans some is still a completed pass over
+        // the pool, not an incomplete one. Gating the event on zero advisory ops
+        // meant it was never emitted in practice, which kept the pool-delta gate
+        // permanently bootstrapped. Record the unapplied count for reporting
+        // instead of withholding the event.
+        const advisoryOpsUnapplied = consolidation.planned?.filter((op) => op.op !== "promote").length ?? 0;
+        if (consolidation.ok && !consolidation.dryRun && complete && consolidation.processed > 0) {
             appendEvent({
                 eventType: "consolidate_completed",
                 ref: makeBundleRef(sourceName, "memories/_consolidation"),
@@ -393,6 +416,7 @@ export async function runConsolidationPass(args) {
                     contradicted: consolidation.contradicted,
                     failedChunks: consolidation.failedChunks ?? 0,
                     durationMs: consolidation.durationMs,
+                    advisoryOpsUnapplied,
                 },
             }, eventsCtx);
         }
@@ -408,7 +432,16 @@ export async function runConsolidationPass(args) {
         }, eventsCtx);
         info("[improve] consolidation skipped (no memory updates since last run)");
     }
-    // D9: track whether consolidation wrote any data so graph extraction can reindex if needed
+    // D9: track whether this was a qualifying consolidation cycle for R5's longitudinal collapse
+    // detector (loop-stages.ts, gated on this flag). `processed` counts memories the LLM JUDGED,
+    // not files consolidation WROTE — R4's advisory gate (consolidate.ts) means merge/delete/
+    // contradict ops are never auto-applied, and the only op that does execute, promote, calls
+    // emitProposal → createProposal, which persists to the `proposals` table in state.db, not to
+    // any file under the stash (src/commands/proposal/repository.ts). So `processed > 0` is the
+    // right gate here: the detector needs one snapshot per cycle where consolidate did work,
+    // regardless of whether that work produced a write. It would be the wrong gate for anything
+    // that needs to know whether a stash file changed, since promote/merge/delete/contradict never
+    // write one.
     const consolidationRan = !consolidateDisabledByProfile &&
         !poolBelowMinSize &&
         !consolidationOnCooldown &&

package/dist/commands/improve/reflect.js

@@ -48,7 +48,8 @@ import { collectDispatchSensitiveValues } from "../../integrations/agent/runner-
 import { isJsonSchemaKnownUnsupported, LlmCallError } from "../../llm/client.js";
 import { callStructured } from "../../llm/structured-call.js";
 import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/agent-support.js";
-import { isProposalSkipped, listProposalsReadOnly, proposalContent, recordGateDecision, } from "../proposal/repository.js";
+import { isStaleTargetRejection } from "../proposal/proposal-types.js";
+import { isProposalSkipped, listProposalsReadOnly, recordGateDecision, } from "../proposal/repository.js";
 import { checkReflectSize, isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
 import { CHARS_PER_TOKEN, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
 import { deriveLessonRef } from "./distill.js";
@@ -75,7 +76,7 @@ const MAX_GLOBAL_FEEDBACK_LINES = 20;
  * all assets so `akm reflect` can operate in a general "review recent
  * signals" mode. Best-effort — a missing or empty events stream returns `[]`.
  */
-function readOnlyEventsContext(ctx) {
+export function readOnlyEventsContext(ctx) {
     return ctx?.db ? ctx : { ...(ctx ?? {}), readOnly: true };
 }
 function readRecentFeedback(ref, eventsCtx) {
@@ -148,13 +149,22 @@ const PROTECTED_FRONTMATTER_FIELDS = new Set(["name", "ref", "id", "slug", "type
 function readRejectedProposals(stash, ref, proposalsCtx) {
     if (!ref)
         return [];
+    // Exclude the drain's stale-target auto-rejects (STALE, R20): those are a
+    // procedural refusal (the target changed after mint), not a judgement on
+    // the content, and would mislead this Reflexion-style "don't repeat this"
+    // context.
     return listProposalsReadOnly(stash, { ref, status: "rejected", includeArchive: true }, proposalsCtx)
+        .filter((p) => !isStaleTargetRejection(p))
         .sort((a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime())
         .slice(0, MAX_REJECTED_PROPOSALS)
         .map((p) => ({
         ref: p.ref,
         reason: p.review?.reason ?? "no reason given",
-        contentPreview: proposalContent(p).slice(0, 500),
+        // #legacy: `changes` is empty for pre-existing rows (storedToChanges),
+        // which makes `proposalContent` throw before reflect dispatch even
+        // runs. `payload.content` is populated for every row regardless, so
+        // read the preview from there instead.
+        contentPreview: p.payload.content.slice(0, 500),
     }));
 }
 /**
@@ -1001,13 +1011,14 @@ async function finalizeReflectProposal(args) {
                     qualityRejected: true,
                     qualityScore: judgeResult.score,
                     qualityReason: judgeResult.reason,
+                    ...(judgeResult.criteria ? { qualityCriteria: judgeResult.criteria } : {}),
                     ...(outputTelemetry ?? {}),
                 },
             }, options.eventsCtx);
             return {
                 schemaVersion: 2,
                 ok: false,
-                reason: "parse_error",
+                reason: "quality_rejected",
                 error: `Reflect proposal quality gate rejected: score=${judgeResult.score}, reason="${judgeResult.reason}"`,
                 ...(options.ref ? { ref: options.ref } : {}),
                 engine: engineName,
@@ -1786,7 +1797,7 @@ export async function akmReflect(options = {}) {
     let qualityJudgeSelection = resolveReflectQualityJudgeRunner(config, runnerSpec, isReflectQualityGateEnabled(activeStrategy), collectExecutionNotices);
     const qualityGateSkippedNoJudge = qualityJudgeSelection.enabled && !qualityJudgeSelection.runner;
     if (qualityGateSkippedNoJudge) {
-        warnOnce("reflect-quality-gate-no-judge", "Reflect proposal quality gate has no LLM configured to judge proposals (set defaults.llmEngine, or improve.strategies.<name>.processes.reflect.qualityGate.engine). Skipping the gate for this run; the proposal is queued for human review instead.");
+        warnOnce("reflect-quality-gate-no-judge", "Reflect proposal quality gate has no LLM configured to judge proposals (set defaults.llmEngine). Skipping the gate for this run; the proposal is queued for human review instead.");
         qualityJudgeSelection = Object.freeze({ enabled: false, runner: undefined });
     }
     const qualityJudgeRunner = qualityJudgeSelection.runner;

package/dist/commands/improve/shared.js

@@ -19,13 +19,3 @@ export const MAX_REJECTED_PROPOSALS = 3;
 export function errMessage(e) {
     return e instanceof Error ? e.message : String(e);
 }
-/**
- * Slugify an asset ref for use in eval-case / rejection filenames: lowercase,
- * non-alphanumerics collapsed to `-`, capped at 60 characters.
- */
-export function refSlug(ref) {
-    return ref
-        .replace(/[^a-z0-9]/gi, "-")
-        .toLowerCase()
-        .slice(0, 60);
-}

package/dist/commands/proposal/drain.js

@@ -38,7 +38,7 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
-import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { computeNormalizedContentHash, parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { ConfigError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
@@ -47,6 +47,7 @@ import { info, warn } from "../../core/warn.js";
 import { acquireLoweredExecutionDispatchLease, dispatchLoweredExecutionRequest, disposeLoweredExecutionDispatchLease, lowerResolvedExecutionRequestWithRunner, } from "../../integrations/agent/execution-lowering.js";
 import { prepareInlineExecutionWithRunner } from "../../integrations/agent/inline-execution.js";
 import { akmProposalAccept, akmProposalReject } from "./proposal.js";
+import { STALE_TARGET_GATE_REASON } from "./proposal-types.js";
 import { listProposals, listProposalsReadOnly, preflightProposalPromotion, proposalContent, recordGateDecision, } from "./repository.js";
 // ---------------------------------------------------------------------------
 // Content helpers
@@ -131,7 +132,7 @@ function deferReasonForSource(source) {
  */
 function categorizeDrainFailure(message, fallback) {
     if (/target (?:changed after|was created after) proposal/.test(message))
-        return "stale-target";
+        return STALE_TARGET_GATE_REASON;
     if (/failed validation:/.test(message))
         return "validation";
     return fallback;
@@ -141,6 +142,33 @@ function pushDrainFailure(result, id, err, fallbackReason) {
     result.failed.push({ id, reason: categorizeDrainFailure(message, fallbackReason), detail: message });
     return message;
 }
+/**
+ * A `stale-target` promote failure (STALE, R20) is not a merit rejection —
+ * the guard tripped because the target changed after mint (often akm's own
+ * bookkeeping), not because of anything wrong with the proposed content. So
+ * instead of leaving the row pending to retry and fail identically every run,
+ * the drain auto-rejects it once with a structured marker.
+ * `checkFingerprintAndBackoff` (repository.ts) excludes this reason from
+ * rejection-backoff, so the ref stays re-proposable against its current
+ * content. Returns `true` when the reject succeeded (the caller should treat
+ * the item as resolved, not failed); `false` leaves it to the caller's
+ * existing failure handling.
+ */
+async function autoRejectStaleTarget(stashDir, gateLabel, id, message, rejectFn) {
+    try {
+        await rejectFn({
+            stashDir,
+            id,
+            reason: `stale-target: ${message}`,
+            gateDecision: { outcome: "auto-rejected", reason: STALE_TARGET_GATE_REASON, gate: gateLabel },
+        });
+        return true;
+    }
+    catch (err) {
+        warn(`[triage] stale-target auto-reject failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
 /**
  * Mirror repository.ts's `promoteProposalWithLease` stale-target guard so a
  * dry-run preflight predicts the same refusal a real promote would hit,
@@ -149,9 +177,17 @@ function pushDrainFailure(result, id, err, fallbackReason) {
  */
 function assertProposalTargetFresh(proposal, assetPath) {
     const backup = fs.existsSync(assetPath) ? fs.readFileSync(assetPath) : undefined;
-    const currentHash = backup ? createHash("sha256").update(backup).digest("hex") : undefined;
-    if (proposal.beforeHash !== undefined && (!backup || currentHash !== proposal.beforeHash)) {
-        throw new Error(`Proposal target changed after proposal ${proposal.id} was created; refusing to overwrite newer content.`);
+    if (proposal.beforeHash !== undefined) {
+        // STALE (R20): mirrors repository.ts's promote guard — a normalized
+        // before-hash is insensitive to a same-run bookkeeping rewrite of the
+        // target; a legacy proposal without one keeps the raw-hash check.
+        const fresh = proposal.beforeHashNormalized !== undefined
+            ? backup !== undefined &&
+                computeNormalizedContentHash(backup.toString("utf8")) === proposal.beforeHashNormalized
+            : backup !== undefined && createHash("sha256").update(backup).digest("hex") === proposal.beforeHash;
+        if (!fresh) {
+            throw new Error(`Proposal target changed after proposal ${proposal.id} was created; refusing to overwrite newer content.`);
+        }
     }
     if (proposal.beforeHash === undefined &&
         backup !== undefined &&
@@ -404,14 +440,20 @@ async function runJudgmentTier(input) {
         if (input.dryRun) {
             try {
                 if (input.config) {
-                    preflightProposalPromotion(input.config, proposal, {
+                    const preflight = preflightProposalPromotion(input.config, proposal, {
                         ...(input.target ? { target: input.target } : {}),
                         gateDecision: { outcome: "auto-accepted", reason: "judgment-accept", gate: input.gateLabel },
                     });
+                    assertProposalTargetFresh(proposal, preflight.assetPath);
                 }
             }
             catch (err) {
-                warn(`[triage] judgment preflight failed for ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
+                const message = err instanceof Error ? err.message : String(err);
+                if (categorizeDrainFailure(message, "promote-error") === STALE_TARGET_GATE_REASON) {
+                    rejected.push(item.id);
+                    continue;
+                }
+                warn(`[triage] judgment preflight failed for ${item.id}: ${message}`);
                 stillDeferred.push(item);
                 continue;
             }
@@ -431,7 +473,13 @@ async function runJudgmentTier(input) {
             acceptBudget -= 1;
         }
         catch (err) {
-            warn(`[triage] judgment promote failed for ${item.id}: ${err instanceof Error ? err.message : String(err)}`);
+            const message = err instanceof Error ? err.message : String(err);
+            if (categorizeDrainFailure(message, "promote-error") === STALE_TARGET_GATE_REASON &&
+                (await autoRejectStaleTarget(input.stashDir, input.gateLabel, item.id, message, input.rejectFn))) {
+                rejected.push(item.id);
+                continue;
+            }
+            warn(`[triage] judgment promote failed for ${item.id}: ${message}`);
             stillDeferred.push(item);
         }
     }
@@ -467,6 +515,16 @@ function classifyPendingProposals(opts) {
         if (proposal.gateDecision?.outcome === "auto-rejected" && !proposal.gateDecision.gate?.startsWith("triage:")) {
             continue;
         }
+        // REVIEW: a `review_needed` distill/promote-memory row is stamped
+        // `deferred`/`quality-gate` by `writeQualityRejection` (distill/quality-gate.ts)
+        // precisely because the quality judge could not decide and wants a human,
+        // not the judgment tier, to see it. Skip it here — before `classifyProposal`
+        // would otherwise defer it to the judgment tier (which can auto-accept
+        // under `applyMode: promote`) and before the policy-deferred re-stamp loop
+        // in `drainProposals` would overwrite this stamp with a `triage:` one.
+        if (proposal.gateDecision?.outcome === "deferred" && proposal.gateDecision.gate === "quality-gate") {
+            continue;
+        }
         if (proposal.gateDecision?.outcome === "staged" &&
             proposal.gateDecision.gate === gateLabel &&
             proposal.gateDecision.contentHash === judgedContentHash(proposal)) {
@@ -588,7 +646,13 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                     deterministicPromoted += 1;
                 }
                 catch (err) {
-                    const message = pushDrainFailure(result, id, err, "promote-error");
+                    const message = err instanceof Error ? err.message : String(err);
+                    if (categorizeDrainFailure(message, "promote-error") === STALE_TARGET_GATE_REASON &&
+                        (await autoRejectStaleTarget(opts.stashDir, gateLabel, id, message, rejectFn))) {
+                        result.rejected.push(id);
+                        continue;
+                    }
+                    pushDrainFailure(result, id, err, "promote-error");
                     warn(`[triage] promote failed for ${id}: ${message}`);
                 }
             }
@@ -618,7 +682,12 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                     deterministicPromoted += 1;
                 }
                 catch (err) {
-                    const message = pushDrainFailure(result, id, err, "promote-error");
+                    const message = err instanceof Error ? err.message : String(err);
+                    if (categorizeDrainFailure(message, "promote-error") === STALE_TARGET_GATE_REASON) {
+                        result.rejected.push(id);
+                        continue;
+                    }
+                    pushDrainFailure(result, id, err, "promote-error");
                     warn(`[triage] preflight failed for ${id}: ${message}`);
                 }
             }

package/dist/commands/proposal/proposal-types.js

@@ -54,3 +54,24 @@ export function isValidProposalSource(source) {
 export function isAutomatedProposalSource(source) {
     return AUTOMATED_PROPOSAL_SOURCES.includes(source);
 }
+/**
+ * Gate-decision reason token for a promote refusal caused by the TARGET
+ * changing after mint — often akm's own bookkeeping, not a merit judgement on
+ * the proposed content (STALE, R20). The drain stamps this on the auto-reject
+ * it issues instead of retrying a promote that will fail identically forever;
+ * {@link isStaleTargetRejection} and the rejection-backoff guard
+ * (`repository.ts`'s `checkFingerprintAndBackoff`) both key off the exact
+ * string so they can't drift apart.
+ */
+export const STALE_TARGET_GATE_REASON = "stale-target";
+/**
+ * True for a rejected proposal whose rejection was the drain's stale-target
+ * auto-reject (STALE, R20), not a judgement on the proposed content. Readers
+ * that treat a rejection as "this content was refused" — the Reflexion
+ * "previously rejected" context (`improve/reflect.ts`, `improve/distill.ts`)
+ * and the accept-rate health metric (`health/accept-rate.ts`) — exclude these
+ * rows so a procedural refusal doesn't misrepresent content quality.
+ */
+export function isStaleTargetRejection(proposal) {
+    return (proposal.gateDecision?.outcome === "auto-rejected" && proposal.gateDecision.reason === STALE_TARGET_GATE_REASON);
+}