akm-cli 0.8.0-rc2 → 0.8.1

package/dist/commands/history.js

@@ -1,21 +1,10 @@
-/**
- * `akm history` — surfaces internal mutation/usage events for a single asset
- * (`--ref`) or stash-wide.
- *
- * Event sources:
- *   - `usage_events` SQLite table: search, show, and feedback events recorded
- *     by the local indexer during normal CLI use.
- *   - `events.jsonl` append-only stream (opt-in via `--include-proposals`):
- *     proposal lifecycle events (`promoted`, `rejected`) emitted by
- *     `akm proposal accept` / `akm proposal reject`. Use this flag to see
- *     the full proposal review trail alongside usage events.
- *
- * The two sources are merged and sorted chronologically (oldest first) so
- * consumers see a coherent lifecycle trail in a single output.
- */
+// 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/.
 import { parseAssetRef } from "../core/asset-ref";
 import { UsageError } from "../core/errors";
 import { readEvents } from "../core/events";
+import { listProposals } from "../core/proposals";
 import { isoToSqlite, parseSinceToIso } from "../core/time";
 import { closeDatabase, openExistingDatabase } from "../indexer/db";
 // Proposal lifecycle event types emitted by the proposal substrate (#225).
@@ -39,6 +28,7 @@ function toEntry(row) {
         entryId: row.entry_id,
         query: row.query,
         signal: row.signal,
+        source: row.source,
         metadata: parseMetadata(row.metadata),
         createdAt: row.created_at,
     };
@@ -91,8 +81,12 @@ export async function akmHistory(options = {}) {
             conditions.push("created_at >= ?");
             params.push(sinceNormalized);
         }
+        if (options.source !== undefined) {
+            conditions.push("source = ?");
+            params.push(options.source);
+        }
         const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-        const sql = `SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, created_at
+        const sql = `SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, source, created_at
                  FROM usage_events ${where}
                  ORDER BY id ASC`;
         const rows = db.prepare(sql).all(...params);
@@ -127,6 +121,7 @@ export async function akmHistory(options = {}) {
                     entryId: null,
                     query: null,
                     signal: null,
+                    source: null,
                     metadata: event.metadata ?? null,
                     createdAt,
                 });
@@ -142,6 +137,45 @@ export async function akmHistory(options = {}) {
                 return 1;
             return a.id - b.id;
         });
+        // ── Accept-rate-per-source (F-4 / #385) ─────────────────────────────────
+        let acceptRateBySource;
+        if (options.acceptRateBySource) {
+            const stashDir = options.stashDir;
+            if (stashDir) {
+                const bySource = new Map();
+                const countProposals = (statuses, includeArchive) => {
+                    for (const status of statuses) {
+                        const proposals = listProposals(stashDir, { status, includeArchive });
+                        for (const p of proposals) {
+                            const src = p.source || "(unknown)";
+                            const entry = bySource.get(src) ?? { accepted: 0, rejected: 0, pending: 0 };
+                            if (status === "accepted")
+                                entry.accepted++;
+                            else if (status === "rejected")
+                                entry.rejected++;
+                            else
+                                entry.pending++;
+                            bySource.set(src, entry);
+                        }
+                    }
+                };
+                countProposals(["pending"], false);
+                countProposals(["accepted", "rejected"], true);
+                acceptRateBySource = Array.from(bySource.entries())
+                    .map(([source, counts]) => {
+                    const decided = counts.accepted + counts.rejected;
+                    return {
+                        source,
+                        total: decided + counts.pending,
+                        accepted: counts.accepted,
+                        rejected: counts.rejected,
+                        pending: counts.pending,
+                        acceptRate: decided > 0 ? counts.accepted / decided : null,
+                    };
+                })
+                    .sort((a, b) => b.total - a.total); // Most active source first
+            }
+        }
         const response = {
             schemaVersion: 1,
             ...(normalizedRef !== undefined ? { ref: normalizedRef } : {}),
@@ -149,6 +183,7 @@ export async function akmHistory(options = {}) {
             totalCount: entries.length,
             entries,
             sources,
+            ...(acceptRateBySource !== undefined ? { acceptRateBySource } : {}),
         };
         return response;
     }

package/dist/commands/improve-auto-accept.js

@@ -0,0 +1,97 @@
+// 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/.
+import { loadConfig } from "../core/config";
+import { appendEvent } from "../core/events";
+import { promoteProposal } from "../core/proposals";
+import { info, warn } from "../core/warn";
+// ---------------------------------------------------------------------------
+// Gate implementation
+// ---------------------------------------------------------------------------
+/**
+ * Attempt to auto-accept each candidate proposal whose confidence meets the
+ * effective threshold. Safe to call unconditionally — returns all-empty when
+ * the gate is disabled or the run is a dry-run.
+ *
+ * @param candidates  Proposals to evaluate, each with an optional confidence.
+ * @param cfg         Gate configuration (phase label, thresholds, context).
+ * @param promoteFn   Injectable override for `promoteProposal` (test seam).
+ */
+export async function runAutoAcceptGate(candidates, cfg, promoteFn = promoteProposal) {
+    const result = { promoted: [], skipped: [], failed: [] };
+    // --- Guard: gate is disabled or context is incomplete ---
+    if (cfg.dryRun || cfg.globalThreshold === undefined || !cfg.stashDir) {
+        result.skipped = candidates.map((c) => c.proposalId);
+        return result;
+    }
+    const effectiveThreshold = Math.max(cfg.globalThreshold, cfg.minimumThreshold ?? 0) / 100;
+    const resolvedConfig = typeof cfg.config === "function" ? cfg.config() : cfg.config;
+    for (const candidate of candidates) {
+        const { proposalId, confidence } = candidate;
+        if (confidence === undefined || confidence < effectiveThreshold) {
+            result.skipped.push(proposalId);
+            continue;
+        }
+        try {
+            const promotion = await promoteFn(cfg.stashDir, resolvedConfig, proposalId, {}, undefined);
+            appendEvent({
+                eventType: "promoted",
+                ref: promotion.ref,
+                metadata: {
+                    proposalId: promotion.proposal.id,
+                    source: promotion.proposal.source,
+                    ...(promotion.proposal.sourceRun !== undefined ? { sourceRun: promotion.proposal.sourceRun } : {}),
+                    assetPath: promotion.assetPath,
+                    autoAccept: true,
+                    confidence,
+                    threshold: effectiveThreshold,
+                    phase: cfg.phase,
+                },
+            }, cfg.eventsCtx ?? {});
+            info(`[improve] auto-accepted ${promotion.ref} (${cfg.phase}; confidence=${confidence.toFixed(2)} >= threshold=${effectiveThreshold.toFixed(2)})`);
+            result.promoted.push(proposalId);
+        }
+        catch (err) {
+            warn(`[improve] ${cfg.phase} auto-accept failed for ${proposalId}: ${err instanceof Error ? err.message : String(err)}`);
+            result.failed.push(proposalId);
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Confidence resolvers
+// ---------------------------------------------------------------------------
+/**
+ * Read the confidence value for an extract proposal.
+ * Extract stores confidence at `payload.frontmatter.confidence` (set by
+ * extract.ts when the LLM response is parsed), not at the top-level field.
+ */
+export function resolveExtractConfidence(proposal) {
+    const fm = proposal.payload.frontmatter;
+    const fmConf = fm?.confidence;
+    if (typeof fmConf === "number")
+        return fmConf;
+    // Fall back to top-level in case a future extract version normalises the path
+    if (typeof proposal.confidence === "number")
+        return proposal.confidence;
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Config builder helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build a gate config for a phase, inheriting global settings from the
+ * improve options. Callers supply only the phase-specific overrides.
+ */
+export function makeGateConfig(phase, shared, overrides = {}) {
+    return {
+        phase,
+        globalThreshold: shared.globalThreshold,
+        dryRun: shared.dryRun,
+        stashDir: shared.stashDir,
+        config: shared.config,
+        eventsCtx: shared.eventsCtx,
+        ...overrides,
+    };
+}
+export { loadConfig };

package/dist/commands/improve-cli.js

@@ -0,0 +1,236 @@
+// 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/.
+import path from "node:path";
+import { defineCommand } from "citty";
+import { getStringArg, parseAutoAcceptFlag, parseNonNegativeIntFlag, parsePositiveIntFlag } from "../cli/parse-args";
+import { output, runWithJsonErrors } from "../cli/shared";
+import { loadConfig } from "../core/config";
+import { UsageError } from "../core/errors";
+import { getCacheDir } from "../core/paths";
+import { clearLogFile, setLogFile } from "../core/warn";
+import { resolveSourceEntries } from "../indexer/search-source";
+import { getHyphenatedArg, getHyphenatedBoolean, parseFlagValue } from "../output/context";
+import { akmImprove } from "./improve";
+import { buildImproveRunId, recordTerminatedImproveRun, relativeImproveResultPath, writeImproveResultFile, } from "./improve-result-file";
+export const improveCommand = defineCommand({
+    meta: {
+        name: "improve",
+        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when profiles.improve.default.processes.consolidate.enabled is true",
+    },
+    args: {
+        scope: {
+            type: "positional",
+            description: "Optional asset type or asset ref to improve",
+            required: false,
+        },
+        task: { type: "string", description: "Add extra guidance for this improvement pass" },
+        "dry-run": { type: "boolean", description: "Show planned actions without writing", default: false },
+        target: { type: "string", description: "Override the write target for accepted proposals" },
+        "auto-accept": {
+            type: "string",
+            description: "Auto-accept proposals at or above this confidence threshold (0-100). Default: disabled. Pass a value 0-100 to enable. 'safe' is an alias for 90. Pass 'false' to be explicit.",
+        },
+        limit: { type: "string", description: "Maximum number of assets to process (highest utility first)" },
+        "timeout-ms": {
+            type: "string",
+            description: "Wall-clock budget for the entire run in milliseconds (default: 7200000 = 2 hours)",
+        },
+        "consolidate-recovery": {
+            type: "string",
+            description: "How to handle stale/incomplete consolidation journals: abort (default) or clean (remove stale journal artifacts)",
+        },
+        "require-feedback-signal": {
+            type: "boolean",
+            description: "Only process assets with recent feedback signals (disables retrieval fallback)",
+            default: false,
+        },
+        "min-retrieval-count": {
+            type: "string",
+            description: "Minimum retrieval count for zero-feedback fallback eligibility (default: 1, set 0 to include all assets regardless of retrieval history)",
+        },
+        "json-to-stdout": {
+            type: "boolean",
+            description: "Emit the full JSON result on stdout (legacy behaviour). (0.8.0+: full result is recorded in the improve_runs table of state.db and stdout is empty; use this flag for the prior behaviour, e.g. `akm improve --json-to-stdout | jq`.)",
+            default: false,
+        },
+        profile: {
+            type: "string",
+            description: "Named improve profile from profiles.improve or built-in profiles (default, quick, thorough, memory-focus, graph-refresh). Controls which sub-processes run and which asset types are processed.",
+        },
+        sync: {
+            type: "boolean",
+            description: "Commit (and optionally push) the git-backed primary stash when the run finishes. Use --no-sync to disable. Default: on for git-backed stashes (per profile config).",
+        },
+        push: {
+            type: "boolean",
+            description: "Push after the end-of-run sync commit when writable + remote configured. Use --no-push to commit only. Default: per profile config (true).",
+        },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const formatFlagValue = parseFlagValue(process.argv, "--format");
+            if (formatFlagValue !== undefined) {
+                throw new UsageError(`akm improve does not accept --format. That flag controls output formatting for other commands (search, show, etc.).\n` +
+                    `Did you mean: akm improve (no --format flag)?`, "INVALID_FLAG_VALUE");
+            }
+            const jsonToStdout = getHyphenatedBoolean(args, "json-to-stdout");
+            const autoAcceptRaw = getHyphenatedArg(args, "auto-accept");
+            const autoAccept = parseAutoAcceptFlag(autoAcceptRaw);
+            const targetArg = getStringArg(args, "target");
+            const taskArg = getStringArg(args, "task");
+            const dryRun = getHyphenatedBoolean(args, "dry-run");
+            const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
+            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
+            const consolidateRecoveryRaw = getHyphenatedArg(args, "consolidate-recovery");
+            const consolidateRecovery = consolidateRecoveryRaw === undefined
+                ? undefined
+                : consolidateRecoveryRaw.trim().toLowerCase();
+            if (consolidateRecovery !== undefined && consolidateRecovery !== "abort" && consolidateRecovery !== "clean") {
+                throw new UsageError(`Invalid --consolidate-recovery value: "${consolidateRecoveryRaw}". Must be one of: abort, clean.`, "INVALID_FLAG_VALUE");
+            }
+            const minRetrievalCountRaw = getHyphenatedArg(args, "min-retrieval-count");
+            const minRetrievalCount = parseNonNegativeIntFlag(minRetrievalCountRaw, "--min-retrieval-count");
+            const requireFeedbackSignal = getHyphenatedBoolean(args, "require-feedback-signal");
+            const profileArg = getStringArg(args, "profile");
+            // Only set the keys the user actually passed (citty leaves the flag
+            // undefined unless `--sync`/`--no-sync` / `--push`/`--no-push` appears),
+            // so the resolved profile `sync` block wins by default.
+            const syncFlag = getHyphenatedArg(args, "sync");
+            const pushFlag = getHyphenatedArg(args, "push");
+            const syncOverride = {};
+            if (syncFlag !== undefined)
+                syncOverride.enabled = syncFlag;
+            if (pushFlag !== undefined)
+                syncOverride.push = pushFlag;
+            const improveLogFile = path.join(getCacheDir(), "logs", "improve", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+            setLogFile(improveLogFile);
+            const startedAtMs = Date.now();
+            const startedAtIso = new Date(startedAtMs).toISOString();
+            // Mint the run-id up front so signal handlers can persist a partial
+            // record if the process is killed mid-run. Pre-2026-05-26 the runId
+            // was minted at end-of-run, so SIGTERM'd runs (cron timeout) left no
+            // row in improve_runs and effectively disappeared from `akm health`.
+            const runId = buildImproveRunId();
+            const primaryStashDir = resolveSourceEntries(undefined, loadConfig())[0]?.path;
+            const scopeArg = getStringArg(args, "scope");
+            const inferredScopeMode = (scopeArg ?? "").includes(":") ? "ref" : scopeArg ? "type" : "all";
+            // Signal handler + exception path both flow through this helper so
+            // every abnormal termination produces a row with ok:false and a
+            // reason in metadata.terminated.
+            let runRecorded = false;
+            const persistTerminated = (reason, errorMessage) => {
+                if (runRecorded)
+                    return;
+                if (!primaryStashDir)
+                    return;
+                runRecorded = true;
+                try {
+                    recordTerminatedImproveRun(primaryStashDir, runId, startedAtIso, reason, {
+                        scopeMode: inferredScopeMode,
+                        scopeValue: scopeArg ?? null,
+                        dryRun: Boolean(dryRun),
+                        profile: profileArg ?? null,
+                        ...(errorMessage ? { errorMessage } : {}),
+                    });
+                }
+                catch (err) {
+                    process.stderr.write(`warning: failed to persist terminated improve run ${runId}: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            };
+            const sigtermHandler = () => {
+                persistTerminated("SIGTERM");
+                process.stderr.write(`[improve] received SIGTERM; recorded terminated run ${runId}\n`);
+                process.exit(143);
+            };
+            const sigintHandler = () => {
+                persistTerminated("SIGINT");
+                process.stderr.write(`[improve] received SIGINT; recorded terminated run ${runId}\n`);
+                process.exit(130);
+            };
+            const sighupHandler = () => {
+                persistTerminated("SIGHUP");
+                process.exit(129);
+            };
+            process.once("SIGTERM", sigtermHandler);
+            process.once("SIGINT", sigintHandler);
+            process.once("SIGHUP", sighupHandler);
+            let improveResult;
+            try {
+                improveResult = await akmImprove({
+                    scope: scopeArg,
+                    task: taskArg,
+                    dryRun,
+                    target: targetArg,
+                    autoAccept,
+                    ...(limitRaw !== undefined ? { limit: limitRaw } : {}),
+                    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                    ...(minRetrievalCount !== undefined ? { minRetrievalCount } : {}),
+                    ...(requireFeedbackSignal ? { requireFeedbackSignal } : {}),
+                    ...(profileArg !== undefined ? { profile: profileArg } : {}),
+                    ...(Object.keys(syncOverride).length > 0 ? { sync: syncOverride } : {}),
+                    consolidateOptions: {
+                        target: targetArg,
+                        dryRun,
+                        autoAccept,
+                        task: taskArg,
+                        ...(consolidateRecovery !== undefined ? { recoveryMode: consolidateRecovery } : {}),
+                    },
+                });
+            }
+            catch (err) {
+                // akmImprove threw — record the failure before letting runWithJsonErrors
+                // emit the standard JSON error envelope. Without this, exceptions in
+                // the main loop (LLM provider crash, OOM, etc.) leave no improve_runs
+                // row, matching the SIGTERM gap.
+                persistTerminated("exception", err instanceof Error ? err.message : String(err));
+                throw err;
+            }
+            finally {
+                process.removeListener("SIGTERM", sigtermHandler);
+                process.removeListener("SIGINT", sigintHandler);
+                process.removeListener("SIGHUP", sighupHandler);
+                clearLogFile();
+            }
+            const durationMs = Date.now() - startedAtMs;
+            if (jsonToStdout) {
+                // Legacy / escape-hatch mode: full JSON on stdout, no file write.
+                // Kept for scripts/agents that already pipe to jq.
+                output("improve", improveResult);
+                process.exit(0);
+            }
+            // Default mode (0.8.0+): persist the full result as a row in the
+            // `improve_runs` table of state.db (migration 003) and emit NOTHING
+            // on stdout. The verbose JSON would otherwise scroll earlier progress
+            // logs out of the terminal buffer. The existing `[improve] ...`
+            // progress log lines on stderr remain the canonical console UX —
+            // do NOT add any new console output here.
+            //
+            // Pre-0.8.0 wrote `<stash>/.akm/runs/<run-id>/improve-result.json`;
+            // those files are no longer authored. Query recent runs with:
+            //   sqlite3 "$AKM_DATA_DIR/state.db" \
+            //     "SELECT id, started_at, ok, dry_run FROM improve_runs \
+            //      ORDER BY started_at DESC LIMIT 10"
+            // runId + primaryStashDir minted up-top so signal handlers can record
+            // partial runs; reuse them here for the success path.
+            const resultRef = relativeImproveResultPath(runId);
+            runRecorded = true; // Suppress any late signal-handler write — the success path owns the row now.
+            if (primaryStashDir) {
+                try {
+                    writeImproveResultFile(primaryStashDir, runId, improveResult);
+                }
+                catch (err) {
+                    // Stderr warning on the failure path is preferable to crashing
+                    // the run after all the work has completed.
+                    process.stderr.write(`warning: failed to record improve run ${resultRef}: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+            else {
+                process.stderr.write(`warning: no writable stash directory resolved; improve result not persisted to state.db (use --json-to-stdout to capture)\n`);
+            }
+            // durationMs reserved for future use (no console emission today).
+            void durationMs;
+            process.exit(0);
+        });
+    },
+});

package/dist/commands/improve-profiles.js

@@ -0,0 +1,138 @@
+// 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/.
+import profileDefault from "../assets/profiles/default.json" with { type: "json" };
+import profileGraphRefresh from "../assets/profiles/graph-refresh.json" with { type: "json" };
+import profileMemoryFocus from "../assets/profiles/memory-focus.json" with { type: "json" };
+import profileQuick from "../assets/profiles/quick.json" with { type: "json" };
+import profileThorough from "../assets/profiles/thorough.json" with { type: "json" };
+import { parseAssetRef } from "../core/asset-ref";
+import { warn } from "../core/warn";
+/** Profile name used as the final fallback when nothing else resolves. */
+const FALLBACK_PROFILE_NAME = "default";
+// Built-in default allowed types per process
+export const DEFAULT_ALLOWED_TYPES = {
+    reflect: ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"],
+    distill: ["memory"],
+    consolidate: ["memory"],
+};
+// Built-in profiles are loaded from embedded JSON files in src/assets/profiles/.
+// To add a new profile: create a new .json file there, import it above, and add
+// it to this map. No code change needed beyond those two steps.
+const BUILTIN_PROFILES = {
+    default: profileDefault,
+    quick: profileQuick,
+    thorough: profileThorough,
+    "memory-focus": profileMemoryFocus,
+    "graph-refresh": profileGraphRefresh,
+};
+/**
+ * Default enabled-state for known improve processes when neither the user
+ * profile nor the built-in default profile specifies an override.
+ *
+ * These mirror the legacy `LlmFeatureFlags` defaults so callers that bypass
+ * the profile system (rare — most run through `resolveImproveProfile`) get
+ * the same answer.
+ */
+const IMPROVE_PROCESS_DEFAULTS = {
+    reflect: true,
+    distill: true,
+    consolidate: true,
+    memoryInference: true,
+    graphExtraction: true,
+    validation: false,
+    // session-extraction reads native session files from claude-code / opencode
+    // and queues durable-insight proposals. Default on — opt out via
+    // profiles.improve.default.processes.extract.enabled: false.
+    extract: true,
+    // proposal-queue triage drains the standing backlog. Opt-in (default off),
+    // like `validation` — needs an explicit `enabled: true`.
+    triage: false,
+};
+/**
+ * Compute the effective enabled-state for a named improve process.
+ *
+ * Resolution order: explicit `profile.processes.<name>.enabled` (boolean) →
+ * the built-in {@link IMPROVE_PROCESS_DEFAULTS} fallback → `false`.
+ */
+export function resolveProcessEnabled(processName, profile) {
+    const processes = profile.processes;
+    const entry = processes?.[processName];
+    if (entry && typeof entry.enabled === "boolean")
+        return entry.enabled;
+    return IMPROVE_PROCESS_DEFAULTS[processName] ?? false;
+}
+function deepMerge(base, override) {
+    if (typeof base !== "object" || base === null)
+        return override ?? base;
+    const result = { ...base };
+    for (const key of Object.keys(override)) {
+        const ov = override[key];
+        // Treat `null` the same as `undefined` so user overrides never wipe a
+        // built-in field with `null`. The on-disk parser already strips nulls,
+        // but the programmatic API exposes this path and callers occasionally
+        // pass JSON-shaped objects with explicit nulls.
+        if (ov !== undefined && ov !== null) {
+            const bv = base[key];
+            if (typeof bv === "object" && bv !== null && typeof ov === "object" && ov !== null && !Array.isArray(bv)) {
+                result[key] = deepMerge(bv, ov);
+            }
+            else {
+                result[key] = ov;
+            }
+        }
+    }
+    return result;
+}
+export function resolveImproveProfile(name, config) {
+    const requestedName = name ??
+        (typeof config.defaults?.improve === "string" ? config.defaults.improve : undefined) ??
+        FALLBACK_PROFILE_NAME;
+    const hasBuiltin = requestedName in BUILTIN_PROFILES;
+    const hasUserDefined = !!config.profiles?.improve?.[requestedName];
+    let effectiveName = requestedName;
+    if (!hasBuiltin && !hasUserDefined && requestedName !== FALLBACK_PROFILE_NAME) {
+        warn(`[akm] Improve profile "${requestedName}" not found in built-ins or config. ` +
+            `Falling back to "${FALLBACK_PROFILE_NAME}".`);
+        effectiveName = FALLBACK_PROFILE_NAME;
+    }
+    const builtin = BUILTIN_PROFILES[effectiveName] ?? BUILTIN_PROFILES[FALLBACK_PROFILE_NAME];
+    const userOverride = config.profiles?.improve?.[effectiveName] ?? {};
+    return deepMerge(builtin, userOverride);
+}
+export function shouldSkipRef(ref, processName, profile) {
+    const cfg = profile.processes?.[processName];
+    // Check if the process itself is disabled
+    if (cfg?.enabled === false)
+        return { skip: true, reason: "process-disabled" };
+    const parsed = parseAssetRef(ref);
+    const allowed = cfg?.allowedTypes ?? DEFAULT_ALLOWED_TYPES[processName];
+    if (!allowed.includes(parsed.type))
+        return { skip: true, reason: "type-filter" };
+    // Hardcoded: wiki raw directories are never processed by any improve process.
+    if (parsed.type === "wiki" && parsed.name.split("/")[1] === "raw") {
+        return { skip: true, reason: "raw-wiki" };
+    }
+    return { skip: false, reason: "" };
+}
+/**
+ * Planner-level pre-filter: return `true` when every per-ref improve pass that
+ * participates in the in-loop dispatch (today: `reflect` and `distill`) would
+ * refuse this ref under the active profile. Such refs cannot produce any work
+ * downstream — they only generate synthetic skip actions and inflate
+ * `plannedRefs` by a constant factor per cron run.
+ *
+ * Companion to `shouldSkipRef`. The 2026-05-27 planner/profile/metrics deep
+ * analysis (`/tmp/akm-health-investigations/planner-profile-metrics-deep-analysis.md`)
+ * documents the 99.07% synthetic-skip emission rate this pre-filter eliminates.
+ *
+ * NOTE: passes that operate on their own candidate set (consolidate,
+ * memoryInference, graphExtraction) are deliberately excluded — they do not
+ * iterate `plannedRefs` per-ref, so a ref being profile-incompatible at the
+ * reflect+distill layer says nothing about their work.
+ */
+export function isProfileFilteredForAllPasses(ref, profile) {
+    const reflectSkip = shouldSkipRef(ref, "reflect", profile);
+    const distillSkip = shouldSkipRef(ref, "distill", profile);
+    return reflectSkip.skip && distillSkip.skip;
+}