akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/commands/improve/improve-strategies.js

@@ -4,12 +4,11 @@
 import catchup from "../../assets/improve-strategies/catchup.json" with { type: "json" };
 import consolidate from "../../assets/improve-strategies/consolidate.json" with { type: "json" };
 import defaultStrategy from "../../assets/improve-strategies/default.json" with { type: "json" };
-import graphRefresh from "../../assets/improve-strategies/graph-refresh.json" with { type: "json" };
 import proactiveMaintenance from "../../assets/improve-strategies/proactive-maintenance.json" with { type: "json" };
 import quick from "../../assets/improve-strategies/quick.json" with { type: "json" };
 import reflectDistill from "../../assets/improve-strategies/reflect-distill.json" with { type: "json" };
 import thorough from "../../assets/improve-strategies/thorough.json" with { type: "json" };
-import { parseRefInput } from "../../core/asset/resolve-ref.js";
+import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { ImproveProfileConfigSchema } from "../../core/config/config-schema.js";
 import { deepMergeConfig } from "../../core/config/deep-merge.js";
 import { BUILTIN_IMPROVE_STRATEGY_NAMES, IMPROVE_PROCESS_ENGINE_CAPABILITIES, } from "../../core/config/engine-semantics.js";
@@ -17,6 +16,7 @@ import { ConfigError } from "../../core/errors.js";
 import { describeLlmCredentialAvailability } from "../../integrations/agent/engine-resolution.js";
 import { applyAutonomyGate } from "./autonomy-gate.js";
 import { resolveImproveExecution, resolveImproveLlmExecution } from "./execution.js";
+import { stripBundle } from "./ledger.js";
 export const DEFAULT_ALLOWED_TYPES = {
     reflect: ["agent", "command", "knowledge", "lesson", "memory", "skill", "workflow"],
     distill: ["memory"],
@@ -27,6 +27,10 @@ export function resolveProcessEnabled(processName, strategy) {
     const processes = strategy.processes;
     return processes?.[processName]?.enabled === true;
 }
+/** An `excludeRefPrefixes` entry as a bare conceptId without a trailing `/` (else `startsWith(".../raw//")` never matches). */
+function stripBundlePrefix(value) {
+    return stripBundle(value).replace(/\/+$/, "");
+}
 export function shouldSkipRef(ref, processName, strategy) {
     const process = strategy.processes?.[processName];
     if (process?.enabled === false)
@@ -35,8 +39,30 @@ export function shouldSkipRef(ref, processName, strategy) {
     const allowed = process?.allowedTypes ?? DEFAULT_ALLOWED_TYPES[processName];
     if (!allowed.includes(parsed.type))
         return { skip: true, reason: "type-filter" };
+    // R12: reflect only — raw wiki-ingest snapshots are type `knowledge`, so
+    // allowedTypes alone can't exclude them (distill/consolidate are memory-only).
+    if (processName === "reflect") {
+        const excludePrefixes = strategy.processes?.reflect?.excludeRefPrefixes;
+        if (excludePrefixes && excludePrefixes.length > 0) {
+            const conceptId = conceptIdFromTypeName(parsed.type, parsed.name);
+            const excluded = excludePrefixes.some((prefix) => {
+                const stripped = stripBundlePrefix(prefix);
+                return conceptId === stripped || conceptId.startsWith(`${stripped}/`);
+            });
+            if (excluded)
+                return { skip: true, reason: "exclude-filter" };
+        }
+    }
     return { skip: false, reason: "" };
 }
+const REF_SCOPED_PROCESSES = new Set(["reflect", "distill", "consolidate"]);
+/** How many refs a ref-scoped process would act on (`undefined` for any other process). */
+export function eligibleRefCount(refs, process, strategy) {
+    if (!REF_SCOPED_PROCESSES.has(process))
+        return undefined;
+    const name = process;
+    return refs.filter((entry) => !shouldSkipRef(entry.ref, name, strategy).skip).length;
+}
 export function isStrategyFilteredForAllPasses(ref, strategy) {
     return shouldSkipRef(ref, "reflect", strategy).skip && shouldSkipRef(ref, "distill", strategy).skip;
 }
@@ -44,7 +70,6 @@ const BUILTIN_STRATEGIES = {
     default: defaultStrategy,
     quick,
     thorough,
-    "graph-refresh": graphRefresh,
     consolidate,
     catchup,
     "reflect-distill": reflectDistill,
@@ -56,6 +81,29 @@ if (BUILTIN_IMPROVE_STRATEGY_NAMES.some((name) => !(name in BUILTIN_STRATEGIES))
 export function resolveImproveStrategy(name, config) {
     const selectedName = name ?? config.defaults?.improveStrategy ?? "default";
     const userStrategies = config.improve?.strategies ?? {};
+    // graph-refresh named a specific, common retirement — refuse it
+    // unconditionally, even when `improve.strategies["graph-refresh"]` still
+    // has an override block from when it customized the (now-deleted) built-in
+    // strategy of the same name. That override is a partial patch (e.g. just
+    // `processes.graphExtraction.mode`), not a full strategy definition —
+    // falling through to the generic "resolve as a user strategy" path below
+    // would silently merge it onto `default` and run a full, unplanned improve
+    // pass instead of refusing. `akm migrate apply` drops the leftover block
+    // (src/core/config/config.ts, normalizeConfigFile) since it can never
+    // apply again.
+    if (selectedName === "graph-refresh") {
+        const hasLeftoverOverride = Boolean(userStrategies["graph-refresh"]);
+        throw new ConfigError(`Improve strategy "graph-refresh" was retired in 0.9.17-alpha.9 along with the LLM entity-graph extraction it ran.` +
+            (hasLeftoverOverride
+                ? ' Your config still has a leftover `improve.strategies["graph-refresh"]` override for it — `akm migrate apply` removes it.'
+                : ""), "UNKNOWN_IMPROVE_STRATEGY", 
+        // Override CONFIG_HINTS.UNKNOWN_IMPROVE_STRATEGY (src/core/errors.ts):
+        // its "listed strategy names" phrase does not apply here (this message
+        // names no strategies), and its "define it under improve.strategies"
+        // suggestion is actively wrong — that is exactly the leftover-override
+        // shape this refusal exists to reject, not a way around it.
+        "Choose a different strategy. `graph-refresh` cannot be redefined under `improve.strategies` — it always refuses.");
+    }
     if (!(selectedName in BUILTIN_STRATEGIES) && !userStrategies[selectedName]) {
         const valid = [...new Set([...Object.keys(BUILTIN_STRATEGIES), ...Object.keys(userStrategies)])].sort();
         throw new ConfigError(`Improve strategy "${selectedName}" not found. Valid strategies: ${valid.join(", ")}.`, "UNKNOWN_IMPROVE_STRATEGY");
@@ -118,7 +166,7 @@ export function projectResolvedProcessRouting(plan) {
     }
     return rows;
 }
-function cloneAndFreeze(value) {
+export function cloneAndFreeze(value) {
     const clone = structuredClone(value);
     const freeze = (item) => {
         if (typeof item !== "object" || item === null || Object.isFrozen(item))

package/dist/commands/improve/improve-usage-report.js

@@ -2,32 +2,22 @@
 // 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/.
 /**
- * #944 — per-run LLM usage reporting: fold the process x engine x model
- * cross-tab (`summarizeLlmUsageCrossTab`, `health/llm-usage.ts`) together with
- * the resolved process routing table (`projectResolvedProcessRouting`, #947)
- * into the `usageReport` field `finalizeImproveResult` persists, and render
- * both halves as one fixed-width table shared by the end-of-run stderr
- * summary (`improve-cli.ts`) and `akm improve report`'s text output
- * (`src/output/text/improve-report.ts`).
+ * The per-run LLM usage report (#944): the process × engine × model cross-tab
+ * plus the enabled processes that made no call and why, rendered as one table
+ * for the end-of-run stderr summary and `akm improve report`.
  */
 import { IMPROVE_PROCESS_ENGINE_CAPABILITIES } from "../../core/config/engine-semantics.js";
-import { projectResolvedProcessRouting, shouldSkipRef, } from "./improve-strategies.js";
+import { eligibleRefCount, projectResolvedProcessRouting, } from "./improve-strategies.js";
 /**
- * The processes this report covers — only the ones {@link IMPROVE_PROCESS_ENGINE_CAPABILITIES}
- * marks `"llm"`. `triage` ("runner" kind — its LLM cost, if any, is
- * attributed to the separate `"triage.judgment"` pseudo-row, itself excluded
- * below) and `proactiveMaintenance` (no engine at all) never make an
- * attributable LLM call, so listing them as "zero calls" would always be a
- * false positive, not a real finding.
+ * Only processes that call an LLM themselves: triage (a runner, attributed to
+ * its judgment engine) and proactive maintenance (no engine) would always read
+ * as "zero calls".
  */
 const LLM_BACKED_PROCESSES = new Set(Object.keys(IMPROVE_PROCESS_ENGINE_CAPABILITIES).filter((name) => IMPROVE_PROCESS_ENGINE_CAPABILITIES[name] === "llm"));
-/** Ref-scoped processes `shouldSkipRef` understands — the only ones an eligible-ref count is meaningful for. */
-const REF_SCOPED_PROCESSES = new Set(["reflect", "distill", "consolidate"]);
-/** The autonomy lane (if any) gating each LLM-backed process, per `autonomy-gate.ts`'s `AUTONOMY_LANES`. */
+/** The autonomy lane gating each LLM-backed process, if any. */
 const AUTONOMY_LANE_BY_PROCESS = {
     memoryInference: "memoryInference",
 };
-/** `{reason -> count}` for the dominant-reason lookup in {@link deriveNoCallReason}. */
 function dominantReason(counts) {
     let best;
     let bestCount = 0;
@@ -40,23 +30,11 @@ function dominantReason(counts) {
     return best;
 }
 /**
- * The single decision point for why an LLM-backed process made zero LLM
- * calls this run — every case `buildImproveUsageReport` needs to report,
- * decided in one place instead of split between this function and its
- * caller. Priority order: `"engine_unavailable"` (the row's engine or
- * credential could not be resolved) beats everything else, including a
- * process that also happens to be autonomy-gated; then, for a disabled row
- * that IS resolvable, `"autonomy_gated"` when its lane was gated, else
- * `undefined` (a `false`-in-config process never reached the routing table
- * in the first place, so a disabled-and-not-gated row has no other
- * explanation to report); for an enabled row, `"strategy_filtered_all_passes"`
- * when every ref got filtered out, then the process's own dominant skip
- * reason, else the `"no_signal"` fallback.
- *
- * Reuses the SAME reason strings already emitted elsewhere
- * (`improve_skipped` events, reflect's `AkmReflectFailure.reason`, distill's
- * `distillSkipped.byReason` keys) rather than inventing a translation layer —
- * per the brief, never a fabricated category like `"limit_reached"`.
+ * Why an LLM-backed process made no call, in priority order: its engine is
+ * unavailable; disabled — `autonomy_gated` when its lane was gated, else
+ * nothing to report; every ref strategy-filtered; its dominant skip reason;
+ * else `no_signal`. The reasons are the ones the events and results already
+ * use.
  */
 export function deriveNoCallReason(args) {
     const { row } = args;
@@ -73,7 +51,7 @@ export function deriveNoCallReason(args) {
         return dominant;
     return "no_signal";
 }
-/** Reflect's per-ref skip reason, read off `AkmReflectFailure.reason` for both cooldown and skipped actions. */
+/** Reflect's skip reasons, from its skipped (and older cooldown) actions. */
 function countReflectSkipReasons(actions) {
     const counts = {};
     for (const action of actions) {
@@ -85,23 +63,9 @@ function countReflectSkipReasons(actions) {
     }
     return counts;
 }
-/**
- * Assemble this run's `usageReport` (#944): the process x engine x model
- * cross-tab plus which enabled processes made zero calls and why. Pure — no
- * I/O; the caller (`finalizeImproveResult`) supplies the cross-tab (already
- * computed from this run's `llm_usage` events) and every other input from
- * data it already has in scope.
- *
- * Returns `undefined` when both halves would be empty (e.g. a run whose
- * active strategy enables no LLM-backed process), matching the envelope's
- * existing convention of omitting empty optional sections.
- */
+/** This run's `usageReport`, or `undefined` when both halves are empty. */
 export function buildImproveUsageReport(args) {
-    // Only the LLM-backed processes (see LLM_BACKED_PROCESSES) — this also
-    // drops the "triage.judgment" pseudo-row (#947): judgment dispatch does
-    // not route through `withLlmStage`, so its calls (if any) are never
-    // attributable to a "triage.judgment" process in the cross-tab, and
-    // reporting it here would always read as a false "zero calls".
+    // The "triage.judgment" row is dropped too: its calls are never attributed to it (#947).
     const routing = projectResolvedProcessRouting(args.resolvedPlan).filter((row) => row.process !== "triage.judgment" && LLM_BACKED_PROCESSES.has(row.process));
     const calledProcesses = new Set(args.byProcessEngineModel.filter((row) => row.calls > 0).map((row) => row.process));
     const reflectSkipCounts = countReflectSkipReasons(args.persistedActions);
@@ -109,9 +73,7 @@ export function buildImproveUsageReport(args) {
     for (const row of routing) {
         if (calledProcesses.has(row.process))
             continue;
-        const eligibleRefs = REF_SCOPED_PROCESSES.has(row.process)
-            ? args.loopRefs.filter((entry) => !shouldSkipRef(entry.ref, row.process, args.resolvedPlan.strategy.config).skip).length
-            : undefined;
+        const eligibleRefs = eligibleRefCount(args.loopRefs, row.process, args.resolvedPlan.strategy.config);
         const reason = deriveNoCallReason({
             row,
             autonomyGated: args.resolvedPlan.autonomyGated,
@@ -131,7 +93,6 @@ export function buildImproveUsageReport(args) {
         return undefined;
     return { byProcessEngineModel: args.byProcessEngineModel, noCalls };
 }
-// ── Shared fixed-width text rendering ────────────────────────────────────────
 function renderFixedWidthTable(headers, rows) {
     const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => row[index]?.length ?? 0)));
     const renderRow = (cells) => cells
@@ -140,14 +101,7 @@ function renderFixedWidthTable(headers, rows) {
         .trimEnd();
     return [renderRow(headers), ...rows.map(renderRow)];
 }
-/**
- * Render a `usageReport` as fixed-width plain text — the ONE formatter shared
- * by the end-of-run `[improve] ...` stderr table (`improve-cli.ts`) and `akm
- * improve report`'s `--format text` output
- * (`src/output/text/improve-report.ts`), per the brief. `notes` surfaces
- * degraded-precision caveats (e.g. a pre-0.9.15 run recomputed from raw
- * events, per `improve-report.ts`).
- */
+/** The usage report as a fixed-width table; `notes` carry precision caveats (e.g. an older run recomputed from events). */
 export function formatUsageReportTable(usageReport, notes) {
     const lines = ["[improve] usage report (process x engine x model):"];
     if (usageReport.byProcessEngineModel.length === 0) {