akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

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

@@ -1,276 +0,0 @@
-// 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/config.js";
-import { UsageError } from "../../core/errors.js";
-import { appendEvent } from "../../core/events.js";
-import { withStateDb } from "../../core/state-db.js";
-import { info, warn } from "../../core/warn.js";
-import { getPhaseThreshold } from "../../storage/repositories/improve-runs-repository.js";
-import { archiveProposal, getProposal, promoteProposal, recordGateDecision } from "../proposal/repository.js";
-async function sha256Hex(input) {
-    const data = new TextEncoder().encode(input);
-    const digest = await crypto.subtle.digest("SHA-256", data);
-    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-/**
- * Derive a stable, low-cardinality reason bucket from an auto-accept promotion
- * error. `promoteProposal` throws a `validateProposal` report formatted as
- * `[kind] message` lines; we extract the first finding kind. Non-validation
- * throws collapse to `promote-error`.
- */
-function classifyPromoteFailure(err) {
-    const message = err instanceof Error ? err.message : String(err);
-    const finding = /\[([a-z][a-z0-9-]*)\]/i.exec(message);
-    if (finding)
-        return `validation:${finding[1]}`;
-    if (/not pending/i.test(message))
-        return "not-pending";
-    if (/unknown asset type/i.test(message))
-        return "unknown-type";
-    return "promote-error";
-}
-// ---------------------------------------------------------------------------
-// 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: [],
-        suppressed: [],
-        failedByReason: {},
-        failedBySource: {},
-    };
-    // --- 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;
-    }
-    // WS-4: per-phase threshold from state.db overrides the global threshold.
-    // The per-phase value is populated by makeGateConfig when a stateDbPath is
-    // available; callers that don't pass it get the global threshold unchanged.
-    const resolvedThreshold = cfg.phaseThreshold ?? cfg.globalThreshold;
-    const effectiveThreshold = Math.max(resolvedThreshold, cfg.minimumThreshold ?? 0) / 100;
-    // WS-4: Exploration budget — promote at most N candidates regardless of
-    // confidence to prevent the gate converging to pure exploitation.
-    // Exploration candidates are chosen from the LOWEST-confidence eligible set
-    // (i.e. those that would be deferred) so the budget truly samples the low-
-    // confidence tail and is meaningfully distinct from normal auto-accept.
-    // Promoted exploration proposals are logged with eligibilitySource="exploration".
-    const explorationBudget = cfg.explorationBudgetCount ?? 0;
-    let explorationRemaining = explorationBudget;
-    const resolvedConfig = typeof cfg.config === "function" ? cfg.config() : cfg.config;
-    const gateLabel = `improve:${cfg.phase}`;
-    // #577: stamp the gate's verdict onto each proposal so `akm proposal show`
-    // can explain why a proposal is pending (e.g. "deferred: below-threshold,
-    // 0.72 < 0.90"). Best-effort — a recording failure must never abort the gate.
-    const stamp = (proposalId, decision) => {
-        try {
-            recordGateDecision(cfg.stashDir, proposalId, decision);
-        }
-        catch (err) {
-            warn(`[improve] ${cfg.phase} failed to record gate decision for ${proposalId}: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    };
-    for (const candidate of candidates) {
-        const { proposalId, confidence } = candidate;
-        let currentProposal;
-        try {
-            currentProposal = cfg.stashDir ? getProposal(cfg.stashDir, proposalId) : undefined;
-        }
-        catch {
-            currentProposal = undefined;
-        }
-        const currentContentHash = currentProposal ? await sha256Hex(currentProposal.payload.content) : undefined;
-        // Determine if this candidate is exploration-eligible: below-threshold
-        // (would normally be deferred) but with a valid confidence score and budget
-        // remaining. No-confidence candidates are never exploration-promoted.
-        const belowThreshold = confidence === undefined || confidence < effectiveThreshold;
-        const isExploration = belowThreshold && confidence !== undefined && explorationRemaining > 0;
-        if (belowThreshold && !isExploration) {
-            stamp(proposalId, {
-                outcome: "deferred",
-                reason: confidence === undefined ? "no-confidence" : "below-threshold",
-                ...(confidence !== undefined ? { confidence } : {}),
-                thresholds: { autoAccept: effectiveThreshold },
-                gate: gateLabel,
-            });
-            result.skipped.push(proposalId);
-            continue;
-        }
-        // Either above-threshold (normal auto-accept) or exploration-budget promoted.
-        if (isExploration)
-            explorationRemaining -= 1;
-        const promoteReason = isExploration ? "exploration-budget" : "above-threshold";
-        if (currentProposal?.gateDecision?.outcome === "auto-rejected" &&
-            currentProposal.gateDecision.contentHash !== undefined &&
-            currentProposal.gateDecision.contentHash === currentContentHash) {
-            result.suppressed.push(proposalId);
-            continue;
-        }
-        try {
-            const promotion = await promoteFn(cfg.stashDir, resolvedConfig, proposalId, {}, undefined);
-            stamp(promotion.proposal.id, {
-                outcome: "auto-accepted",
-                reason: promoteReason,
-                confidence,
-                thresholds: { autoAccept: effectiveThreshold },
-                ...(currentContentHash !== undefined ? { contentHash: currentContentHash } : {}),
-                gate: gateLabel,
-            });
-            // Resolve the eligibilitySource: exploration-promoted proposals get
-            // eligibilitySource="exploration" (WS-4); normal auto-accepts carry
-            // whatever the proposal was tagged with at selection time.
-            const resolvedEligibilitySource = isExploration
-                ? "exploration"
-                : promotion.proposal.eligibilitySource;
-            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,
-                    // Attribution tagging: carry the eligibility lane from the proposal
-                    // record onto the auto-accept promoted event so the lane survives to
-                    // accept time even when promotion happens in a later run.
-                    ...(resolvedEligibilitySource !== undefined ? { eligibilitySource: resolvedEligibilitySource } : {}),
-                    // WS-4: mark exploration promotions so health/telemetry can
-                    // distinguish them from calibration-signal promotions.
-                    ...(isExploration ? { explorationBudget: true } : {}),
-                },
-            }, cfg.eventsCtx ?? {});
-            if (isExploration) {
-                info(`[improve] exploration-accepted ${promotion.ref} (${cfg.phase}; confidence=${confidence.toFixed(2)}; budgetRemaining=${explorationRemaining})`);
-            }
-            else {
-                info(`[improve] auto-accepted ${promotion.ref} (${cfg.phase}; confidence=${confidence.toFixed(2)} >= threshold=${effectiveThreshold.toFixed(2)})`);
-            }
-            result.promoted.push(proposalId);
-        }
-        catch (err) {
-            const reason = classifyPromoteFailure(err);
-            warn(`[improve] ${cfg.phase} auto-accept failed for ${proposalId} (${reason}): ${err instanceof Error ? err.message : String(err)}`);
-            result.failed.push(proposalId);
-            result.failedByReason[reason] = (result.failedByReason[reason] ?? 0) + 1;
-            // Record WHY on the proposal so `akm proposal show` explains the rejection
-            // and the leak is no longer blind. Best-effort.
-            stamp(proposalId, {
-                outcome: "auto-rejected",
-                reason,
-                confidence,
-                thresholds: { autoAccept: effectiveThreshold },
-                ...(currentContentHash !== undefined ? { contentHash: currentContentHash } : {}),
-                gate: gateLabel,
-            });
-            // A validation failure is permanent — the minted content can never satisfy
-            // the asset schema, so archive it as rejected instead of leaving it pending
-            // to be retried on every future run (the 90-day TTL is otherwise the first
-            // thing ever to touch these zombies). Best-effort; ctx=undefined mirrors the
-            // promoteFn call above so the archive hits the same stashDir-derived DB.
-            //
-            // Discriminate on the STRUCTURED error, not the `reason` string: promoteProposal
-            // throws UsageError("MISSING_REQUIRED_ARGUMENT") only for the validateProposal
-            // failure branch. Message-sniffing (`reason` = "validation:<kind>") would also
-            // match a transient git-push rejection ("[rejected] ... non-fast-forward") from
-            // a git-backed write target and permanently archive a valid, retryable proposal.
-            const isPermanentValidationFailure = err instanceof UsageError && err.code === "MISSING_REQUIRED_ARGUMENT";
-            if (isPermanentValidationFailure) {
-                try {
-                    archiveProposal(cfg.stashDir, proposalId, "rejected", `auto-accept ${reason}`, undefined);
-                }
-                catch (archiveErr) {
-                    warn(`[improve] ${cfg.phase} failed to archive validation-failed proposal ${proposalId}: ${archiveErr instanceof Error ? archiveErr.message : String(archiveErr)}`);
-                }
-            }
-            // If exploration budget was consumed but promotion failed, restore the slot
-            // so the budget isn't exhausted on errors.
-            if (isExploration)
-                explorationRemaining += 1;
-        }
-    }
-    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.
- *
- * WS-4 additions:
- * - When `shared.stateDbPath` is provided, reads the persisted per-phase
- *   threshold from `improve_gate_thresholds` (Migration 012). The phase
- *   value overrides `globalThreshold` but is still floored by
- *   `minimumThreshold`. Falls back to `globalThreshold` when no row exists.
- * - Computes `explorationBudgetCount` from
- *   `config.improve.exploration.budgetFraction × candidateCount` when the
- *   exploration budget is enabled. Defaults to 0 (no exploration).
- */
-export function makeGateConfig(phase, shared, overrides = {}) {
-    // WS-4: read per-phase threshold from state.db when available.
-    let phaseThreshold;
-    if (shared.stateDbPath && shared.globalThreshold !== undefined) {
-        try {
-            phaseThreshold = withStateDb((db) => getPhaseThreshold(db, phase) ?? undefined, {
-                path: shared.stateDbPath,
-            });
-        }
-        catch {
-            // DB unavailable — fall back to globalThreshold silently.
-        }
-    }
-    // WS-4: compute exploration budget count from config fraction × candidateCount.
-    let explorationBudgetCount;
-    const resolvedConfig = typeof shared.config === "function" ? shared.config() : shared.config;
-    const explorationCfg = resolvedConfig.improve?.exploration;
-    if (explorationCfg?.enabled && shared.candidateCount !== undefined && shared.candidateCount > 0) {
-        const fraction = Math.min(1, Math.max(0, explorationCfg.budgetFraction ?? 0.05));
-        explorationBudgetCount = Math.max(0, Math.floor(fraction * shared.candidateCount));
-    }
-    return {
-        phase,
-        globalThreshold: shared.globalThreshold,
-        ...(phaseThreshold !== undefined ? { phaseThreshold } : {}),
-        dryRun: shared.dryRun,
-        stashDir: shared.stashDir,
-        config: shared.config,
-        eventsCtx: shared.eventsCtx,
-        ...(explorationBudgetCount !== undefined && explorationBudgetCount > 0 ? { explorationBudgetCount } : {}),
-        ...overrides,
-    };
-}
-export { loadConfig };

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

@@ -1,168 +0,0 @@
-// 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 profileCatchup from "../../assets/profiles/catchup.json" with { type: "json" };
-import profileConsolidate from "../../assets/profiles/consolidate.json" with { type: "json" };
-import profileDefault from "../../assets/profiles/default.json" with { type: "json" };
-import profileFrequent from "../../assets/profiles/frequent.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 profileProactiveMaintenance from "../../assets/profiles/proactive-maintenance.json" with { type: "json" };
-import profileQuick from "../../assets/profiles/quick.json" with { type: "json" };
-import profileRecombineOnly from "../../assets/profiles/recombine-only.json" with { type: "json" };
-import profileReflectDistill from "../../assets/profiles/reflect-distill.json" with { type: "json" };
-import profileSynthesize from "../../assets/profiles/synthesize.json" with { type: "json" };
-import profileThorough from "../../assets/profiles/thorough.json" with { type: "json" };
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
-import { ConfigError } from "../../core/errors.js";
-/** 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,
-    frequent: profileFrequent,
-    consolidate: profileConsolidate,
-    catchup: profileCatchup,
-    synthesize: profileSynthesize,
-    "reflect-distill": profileReflectDistill,
-    "proactive-maintenance": profileProactiveMaintenance,
-    "recombine-only": profileRecombineOnly,
-};
-/**
- * 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,
-    // Layer 2 proactive-maintenance selector. Opt-in (default off) — surfaces
-    // stale high-value assets on a schedule. Enable per-profile with an explicit
-    // `processes.proactiveMaintenance.enabled: true`.
-    proactiveMaintenance: false,
-    // #609 recombine / synthesize pass — whole-corpus cross-episodic
-    // generalization. Opt-in (default off); enable per-profile with an explicit
-    // `processes.recombine.enabled: true`.
-    recombine: false,
-    // #615 procedural-compilation pass — detects recurring successful ordered
-    // action sequences and compiles them into workflow proposals. Opt-in (default
-    // off); enable per-profile with an explicit `processes.procedural.enabled: true`.
-    procedural: 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];
-    // An unknown profile name is a HARD error. Silently falling back to the
-    // default (proactive-off) profile is the −96% incident class: a cron pinned
-    // to `--profile reflect-distill` ran the default for weeks because the name
-    // only existed in one host's config and the resolver swallowed the miss.
-    if (!hasBuiltin && !hasUserDefined) {
-        const valid = [
-            ...new Set([...Object.keys(BUILTIN_PROFILES), ...Object.keys(config.profiles?.improve ?? {})]),
-        ].sort();
-        throw new ConfigError(`Improve profile "${requestedName}" not found. Valid profiles: ${valid.join(", ")}.`, "UNKNOWN_IMPROVE_PROFILE");
-    }
-    const builtin = BUILTIN_PROFILES[requestedName] ?? BUILTIN_PROFILES[FALLBACK_PROFILE_NAME];
-    const userOverride = config.profiles?.improve?.[requestedName] ?? {};
-    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;
-}