akm-cli 0.9.0-beta.1 → 0.9.0-beta.11

package/dist/commands/improve/proactive-maintenance.js

@@ -0,0 +1,113 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/** One day in milliseconds. */
+const DAY_MS = 86_400_000;
+/**
+ * Importance multipliers by asset type. Higher = more worth maintaining. These
+ * are the design defaults; callers may override any subset via config.
+ */
+export const DEFAULT_IMPORTANCE_WEIGHTS = Object.freeze({
+    skill: 1.5,
+    agent: 1.5,
+    command: 1.3,
+    workflow: 1.3,
+    lesson: 1.2,
+    knowledge: 1.0,
+    script: 0.9,
+    memory: 0.7,
+});
+/** Default staleness gate: an asset is due when last reflected > this many days ago (or never). */
+export const DEFAULT_DUE_DAYS = 30;
+/** Default bound on how many assets the selector surfaces per run. */
+export const DEFAULT_MAX_PER_RUN = 25;
+/**
+ * Half-life (days) for the recency-of-use decay term. An asset used today
+ * contributes a full recency multiplier; one unused for one half-life
+ * contributes half. Mirrors the validated prototype (21 days).
+ */
+const RECENCY_HALFLIFE_DAYS = 21;
+/** Lower bound on size used in the cost denominator so tiny files don't divide by ~0. */
+const SIZE_FLOOR_BYTES = 200;
+/** Parse the bare asset type out of a `type:name` ref. Returns "" when unparseable. */
+function refType(ref) {
+    const i = ref.indexOf(":");
+    return i > 0 ? ref.slice(0, i) : "";
+}
+/**
+ * Score and select due assets for proactive maintenance.
+ *
+ * Priority formula (mirrors the validated prototype):
+ *
+ *   priority = (importance × log(1 + retrievalFreq) × (0.1 + 0.5^(useAgeDays/21)))
+ *              / log10(max(size, 200))
+ *
+ * DUE gate: an asset is eligible only if it was never reflected OR last
+ * reflected/distilled more than `dueDays` ago. The same gate doubles as the
+ * ROTATION cooldown — a freshly-reflected asset is excluded until it ages back
+ * past `dueDays`, so successive runs rotate through the due pool rather than
+ * re-selecting the same heads. Non-due assets never enter the selection.
+ */
+export function selectProactiveMaintenanceRefs(params) {
+    const now = params.now ?? Date.now();
+    const dueDays = params.dueDays ?? DEFAULT_DUE_DAYS;
+    const maxPerRun = params.maxPerRun ?? DEFAULT_MAX_PER_RUN;
+    const weights = { ...DEFAULT_IMPORTANCE_WEIGHTS, ...(params.importanceWeights ?? {}) };
+    const scored = [];
+    for (const candidate of params.candidates) {
+        const ref = candidate.ref;
+        const type = refType(ref);
+        // Staleness from the most recent of reflect/distill — either one touching
+        // the asset resets its maintenance clock.
+        const reflectIso = params.lastReflectTs.get(ref);
+        const distillIso = params.lastDistillTs.get(ref);
+        let lastTouchMs = 0;
+        if (reflectIso)
+            lastTouchMs = Math.max(lastTouchMs, Date.parse(reflectIso) || 0);
+        if (distillIso)
+            lastTouchMs = Math.max(lastTouchMs, Date.parse(distillIso) || 0);
+        const neverReflected = lastTouchMs === 0;
+        const staleDays = neverReflected ? Number.POSITIVE_INFINITY : (now - lastTouchMs) / DAY_MS;
+        // DUE / rotation gate.
+        const due = neverReflected || staleDays > dueDays;
+        // Retrieval frequency + recency decay.
+        const retrievalFreq = params.retrievalCounts.get(ref) ?? 0;
+        const lastUse = params.lastUseMs?.get(ref) ?? 0;
+        const useAgeDays = lastUse > 0 ? (now - lastUse) / DAY_MS : 9999;
+        const recencyDecay = 0.1 + 0.5 ** (useAgeDays / RECENCY_HALFLIFE_DAYS);
+        // Size proxy (cost): larger assets are slightly deprioritized, but only by
+        // log10 so a big-but-hot asset is never starved.
+        let sizeBytes = params.sizeBytesOf?.(candidate) ?? 0;
+        if (!sizeBytes || sizeBytes < 0)
+            sizeBytes = SIZE_FLOOR_BYTES;
+        const sizeProxy = Math.max(SIZE_FLOOR_BYTES, sizeBytes);
+        const importance = weights[type] ?? 1.0;
+        const priority = (importance * Math.log(1 + retrievalFreq) * recencyDecay) / Math.log10(sizeProxy);
+        scored.push({
+            ref: candidate,
+            type,
+            staleDays,
+            neverReflected,
+            retrievalFreq,
+            recencyDecay,
+            sizeBytes,
+            importance,
+            priority,
+            due,
+        });
+    }
+    const dueScored = scored.filter((s) => s.due);
+    const dueTotal = dueScored.length;
+    const neverReflected = dueScored.filter((s) => s.neverReflected).length;
+    // Rank due assets by composite priority (desc). Ties broken by staleness
+    // (older first) then ref string for deterministic ordering.
+    const ranked = dueScored.slice().sort((a, b) => {
+        if (b.priority !== a.priority)
+            return b.priority - a.priority;
+        if (b.staleDays !== a.staleDays)
+            return b.staleDays - a.staleDays;
+        return a.ref.ref < b.ref.ref ? -1 : a.ref.ref > b.ref.ref ? 1 : 0;
+    });
+    const selected = ranked.slice(0, Math.max(0, maxPerRun)).map((s) => s.ref);
+    return { selected, dueTotal, neverReflected, scored };
+}

package/dist/commands/improve/reflect.js

@@ -46,6 +46,7 @@ import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigF
 import { checkReflectSize } from "../proposal/validators/proposal-quality-validators.js";
 import { createProposal, isProposalSkipped, listProposals, } from "../proposal/validators/proposals.js";
 import { deriveLessonRef, runLessonQualityJudge } from "./distill.js";
+import { classifyReflectChange } from "./reflect-noise.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
 /**
@@ -584,6 +585,9 @@ export async function akmReflect(options = {}) {
         metadata: {
             ...(options.task ? { task: options.task } : {}),
             ...(options.profile ? { profile: options.profile } : {}),
+            // Attribution tagging: stamp the eligibility lane so reflect_invoked can be
+            // sliced by lane downstream. See EligibilitySource.
+            ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
         },
     });
     // Fix #3 (observability 0.8.0): every failure path below MUST emit
@@ -1138,6 +1142,30 @@ export async function akmReflect(options = {}) {
         content: sanitizeOutcome.content,
         ...(sanitizeOutcome.frontmatter ? { frontmatter: sanitizeOutcome.frontmatter } : {}),
     };
+    // 7c. Noise gate (#580): never queue a proposal whose sanitized content is
+    // identical to the current asset (empty diff) or differs only cosmetically
+    // (whitespace reflow, code-fence language hints, YAML scalar re-folding).
+    // Pure deterministic text comparison — see `reflect-noise.ts`. Runs before
+    // the draftMode branch so self-consistency sampling never votes a no-op
+    // candidate into the queue either. Skipped when there is no source asset
+    // (new-asset proposals have nothing to diff against).
+    if (assetContent !== undefined) {
+        const changeKind = classifyReflectChange(assetContent, payload.content);
+        if (changeKind !== "substantive") {
+            const subreason = changeKind === "noop" ? "reflect_skipped_noop" : "reflect_skipped_cosmetic";
+            emitReflectFailed("no_change", subreason, options.ref, { changeKind });
+            return {
+                schemaVersion: 1,
+                ok: false,
+                reason: "no_change",
+                error: changeKind === "noop"
+                    ? `Reflect skipped: proposed content for ${payload.ref} is identical to the current asset (empty diff); no proposal created.`
+                    : `Reflect skipped: proposed content for ${payload.ref} is a cosmetic-only reformat of the current asset (whitespace/fence/YAML-folding changes); no proposal created.`,
+                ...(options.ref ? { ref: options.ref } : {}),
+                exitCode: result.exitCode,
+            };
+        }
+    }
     // 8. Create the proposal. The proposal queue is the ONLY thing reflect
     // writes — promotion to a real asset is gated by `akm proposal accept`.
     //
@@ -1203,6 +1231,9 @@ export async function akmReflect(options = {}) {
         // `parseAgentProposalPayload` already clamps to [0, 1] and drops non-
         // finite values; `createProposal` runs its own sanitizer as a safety net.
         ...(typeof payload.confidence === "number" ? { confidence: payload.confidence } : {}),
+        // Attribution tagging: persist the eligibility lane on the proposal so it
+        // survives to accept/reject/revert time even across runs. See EligibilitySource.
+        ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
     };
     const proposalResult = createProposal(stash, createInput, options.ctx);
     if (isProposalSkipped(proposalResult)) {

package/dist/commands/proposal/drain.js

@@ -46,7 +46,7 @@ import { runAgent } from "../../integrations/agent/index.js";
 import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
 import { chatCompletion, stripJsonFences } from "../../llm/client.js";
 import { akmProposalAccept, akmProposalReject } from "./proposal.js";
-import { listProposals } from "./validators/proposals.js";
+import { listProposals, recordGateDecision } from "./validators/proposals.js";
 // ---------------------------------------------------------------------------
 // Content helpers
 // ---------------------------------------------------------------------------
@@ -78,7 +78,7 @@ export function classifyProposal(proposal, policy, maxDiffLines) {
     const content = proposal.payload.content ?? "";
     // Empty / near-empty diffs reject first (the reject-empty floor).
     if (policy.rejectEmpty && isEmptyDiff(proposal)) {
-        return { verdict: "reject", reason: "empty diff" };
+        return { verdict: "reject", reason: "empty diff", gate: { reason: "empty-diff" } };
     }
     const rule = policy.accept.find((r) => r.generator === proposal.source);
     if (rule) {
@@ -87,16 +87,25 @@ export function classifyProposal(proposal, policy, maxDiffLines) {
         // Per-rule and global diff bounds defer large accepts (no silent rewrites).
         const effectiveMax = Math.min(rule.maxDiffLines ?? Number.POSITIVE_INFINITY, maxDiffLines ?? Number.POSITIVE_INFINITY);
         if (lines > effectiveMax) {
-            return { verdict: "defer", reason: "mid-band" };
+            return {
+                verdict: "defer",
+                reason: "mid-band",
+                gate: { reason: "max-diff-lines", measured: lines, thresholds: { maxDiffLines: effectiveMax } },
+            };
         }
         if (rule.minContentLines !== undefined && body < rule.minContentLines) {
             // Too little content to confidently auto-accept — leave for judgment.
-            return { verdict: "defer", reason: "mid-band" };
+            return {
+                verdict: "defer",
+                reason: "mid-band",
+                gate: { reason: "min-content-lines", measured: body, thresholds: { minContentLines: rule.minContentLines } },
+            };
         }
-        return { verdict: "accept" };
+        return { verdict: "accept", gate: { reason: "policy-accept" } };
     }
     if (policy.defer.includes(proposal.source)) {
-        return { verdict: "defer", reason: deferReasonForSource(proposal.source) };
+        const reason = deferReasonForSource(proposal.source);
+        return { verdict: "defer", reason, gate: { reason } };
     }
     // No matching rule — leave pending, untouched.
     return null;
@@ -347,10 +356,31 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
     // First, classify every proposal deterministically.
     const acceptIds = [];
     const rejectTargets = [];
+    const gateLabel = `triage:${opts.policy.name}`;
+    // Items deferred purely because they need a judge (no threshold-based reason)
+    // — these are re-stamped `no-judge-configured` when no runner resolves them.
+    const needsJudge = new Set();
     for (const proposal of pending) {
         const decision = classifyProposal(proposal, opts.policy, opts.maxDiffLines);
         if (decision === null)
             continue;
+        // #577: stamp the gate's verdict onto the proposal so `akm proposal show`
+        // can explain WHY it landed here. A dry-run performs zero writes, so it
+        // records nothing.
+        const outcome = decision.verdict === "accept" ? "auto-accepted" : decision.verdict === "reject" ? "auto-rejected" : "deferred";
+        stampGateDecision(opts, proposal.id, {
+            outcome,
+            reason: decision.gate.reason,
+            ...(decision.gate.measured !== undefined ? { measured: decision.gate.measured } : {}),
+            ...(decision.gate.thresholds ? { thresholds: decision.gate.thresholds } : {}),
+            gate: gateLabel,
+        });
+        // A defer with no threshold (mid-band / possible-dup from the defer list) is
+        // pending only because it needs adjudication — re-stampable to
+        // `no-judge-configured`. A band-based defer keeps its specific reason.
+        if (decision.verdict === "defer" && !decision.gate.thresholds) {
+            needsJudge.add(proposal.id);
+        }
         if (decision.verdict === "accept") {
             acceptIds.push(proposal.id);
         }
@@ -434,14 +464,51 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
         if (tier.skippedByCap.length > 0) {
             info(`[triage] accept ceiling reached in judgment tier: ${tier.skippedByCap.length} judged-accept items skipped by cap (maxAccepts=${opts.maxAccepts})`);
         }
+        // #577: re-stamp the gate decision for items the judgment tier resolved so
+        // `akm proposal show` reflects the judge's verdict, not the earlier
+        // deterministic defer.
+        for (const id of tier.promoted) {
+            stampGateDecision(opts, id, { outcome: "auto-accepted", reason: "judgment-accept", gate: gateLabel });
+        }
+        for (const id of tier.rejected) {
+            stampGateDecision(opts, id, { outcome: "auto-rejected", reason: "judgment-reject", gate: gateLabel });
+        }
         // Replace the deferred list with only the items the judgment tier could NOT
         // resolve (verdict "defer", parse failure, or runner error). Staged
         // queue-mode accepts are RESOLVED and tracked in result.staged instead.
         result.deferred = tier.stillDeferred;
     }
+    else if (result.deferred.length > 0) {
+        // #577: no judgment runner configured — items deferred *because they need a
+        // judge* (mid-band / possible-dup, no threshold reason) stay pending solely
+        // for lack of one. Re-stamp those as `no-judge-configured` so the operator
+        // sees a per-proposal reason instead of inferring it from the run-level
+        // triage_deferred aggregate. Band-deferred items keep their specific reason
+        // (e.g. `max-diff-lines`), which is more actionable than "no judge".
+        for (const item of result.deferred) {
+            if (needsJudge.has(item.id)) {
+                stampGateDecision(opts, item.id, { outcome: "deferred", reason: "no-judge-configured", gate: gateLabel });
+            }
+        }
+    }
     emitDrainEvents(opts, result);
     return result;
 }
+/**
+ * Persist a gate decision onto a proposal, honouring the dry-run contract
+ * (a dry run performs zero writes, so it records nothing) and never letting a
+ * persistence failure abort the drain (#577). Best-effort by design.
+ */
+function stampGateDecision(opts, id, decision) {
+    if (opts.dryRun)
+        return;
+    try {
+        recordGateDecision(opts.stashDir, id, decision);
+    }
+    catch (err) {
+        warn(`[triage] failed to record gate decision for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Events
 // ---------------------------------------------------------------------------

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

@@ -16,6 +16,8 @@ import { resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { resolveTriageJudgmentRunner } from "../../integrations/agent/runner.js";
+import { installLlmUsagePersistenceIfAbsent } from "../../llm/usage-persist.js";
+import { withLlmStage } from "../../llm/usage-telemetry.js";
 import { resolveImproveProfile } from "../improve/improve-profiles.js";
 import { drainProposals } from "./drain.js";
 import { resolveDrainPolicy } from "./drain-policies.js";
@@ -407,16 +409,26 @@ const proposalDrainCommand = defineJsonCommand({
         // nothing is configured → the engine leaves deferred items unresolved and
         // emits triage_deferred.
         const judgment = args.judgment === true ? resolveTriageJudgmentRunner(triageConfig?.judgment, cfg) : null;
-        const result = await drainProposals({
-            stashDir,
-            policy,
-            applyMode,
-            maxAccepts,
-            dryRun,
-            ...(maxDiffLines !== undefined ? { maxDiffLines } : {}),
-            ...(excludeIds ? { excludeIds } : {}),
-            judgment,
-        });
+        // #576: persist + attribute per-call LLM usage for the standalone drain
+        // path. `IfAbsent` keeps an enclosing `akm improve` sink in charge when
+        // drain runs as a sub-step; the disposer clears only a sink we installed.
+        const disposeDrainUsageSink = installLlmUsagePersistenceIfAbsent();
+        let result;
+        try {
+            result = await withLlmStage("drain", () => drainProposals({
+                stashDir,
+                policy,
+                applyMode,
+                maxAccepts,
+                dryRun,
+                ...(maxDiffLines !== undefined ? { maxDiffLines } : {}),
+                ...(excludeIds ? { excludeIds } : {}),
+                judgment,
+            }));
+        }
+        finally {
+            disposeDrainUsageSink();
+        }
         output("proposal-drain", {
             schemaVersion: 1,
             ok: true,

package/dist/commands/proposal/proposal.js

@@ -22,6 +22,17 @@ function resolveStash(stashDir) {
         return stashDir;
     return resolveStashDir();
 }
+/**
+ * Thin in-process read of the pending proposal queue, used by the health HTML
+ * report builder (#582) so it never shells out to `akm proposal list`.
+ *
+ * Deliberately narrow (one optional arg, returns the storage-layer rows) so
+ * the parallel proposal-storage-to-SQLite consolidation only has to swap this
+ * one function's body.
+ */
+export function listPendingProposals(stashDir) {
+    return listProposals(resolveStash(stashDir), { status: "pending" });
+}
 export function akmProposalList(options = {}) {
     const stash = resolveStash(options.stashDir);
     // `--status accepted|rejected|reverted` implies archive-inclusion since the
@@ -64,6 +75,11 @@ export async function akmProposalAccept(options) {
             source: result.proposal.source,
             ...(result.proposal.sourceRun !== undefined ? { sourceRun: result.proposal.sourceRun } : {}),
             assetPath: result.assetPath,
+            // Attribution tagging: carry the eligibility lane from the proposal record
+            // onto the promoted event so accept outcomes can be sliced by lane.
+            ...(result.proposal.eligibilitySource !== undefined
+                ? { eligibilitySource: result.proposal.eligibilitySource }
+                : {}),
         },
     });
     return {
@@ -141,7 +157,7 @@ export function akmProposalCreate(options) {
  *     (raised by `resolveProposalId` / `getProposal`).
  *   - Proposal is not `status === "accepted"` → `UsageError("INVALID_FLAG_VALUE")`
  *     with message `"only accepted proposals can be reverted ..."`.
- *   - No `backup` field, or the backup file is missing on disk →
+ *   - No backup content on the record (new-asset proposals capture none) →
  *     `UsageError` with message `"no backup available for this proposal ..."`.
  *
  * On success, emits a `proposal_reverted` event for observability, mirroring