akm-cli 0.8.0-rc2 → 0.8.0

package/dist/commands/improve-profiles.js

@@ -0,0 +1,184 @@
+// 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 { 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"],
+};
+const BUILTIN_PROFILES = {
+    default: {
+        description: "Standard improve pass — all sub-processes, markdown asset types.",
+        processes: {
+            reflect: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.reflect },
+            distill: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.distill },
+            consolidate: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.consolidate },
+            memoryInference: { enabled: true },
+            graphExtraction: { enabled: true },
+            // validation: deliberately undefined — third-tier classifier is opt-in.
+            triage: { enabled: false, applyMode: "queue", policy: "personal-stash" },
+        },
+        sync: { enabled: true, push: true },
+    },
+    quick: {
+        description: "Reflect-only pass — no distill, consolidate, memoryInference, or graphExtraction.",
+        processes: {
+            reflect: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.reflect },
+            distill: { enabled: false },
+            consolidate: { enabled: false },
+            memoryInference: { enabled: false },
+            graphExtraction: { enabled: false },
+            triage: { enabled: false },
+        },
+        // Lightweight passes opt out of end-of-run sync: a reflect-only `quick`
+        // run should not auto-commit/push the git-backed stash to its remote.
+        // (The auto-sync gate in improve.ts treats an absent sync block as
+        // ENABLED + push, so we set this explicitly to avoid a surprise push.)
+        sync: { enabled: false },
+    },
+    thorough: {
+        // Reserved for future divergence; for now behaviorally identical to
+        // `default`. Documented here so callers picking `--profile thorough` do
+        // not expect a different code path until we wire stricter limits in.
+        description: "All sub-processes enabled (currently identical to default; reserved for future divergence).",
+        processes: {
+            reflect: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.reflect },
+            distill: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.distill },
+            consolidate: { enabled: true, allowedTypes: DEFAULT_ALLOWED_TYPES.consolidate },
+            memoryInference: { enabled: true },
+            graphExtraction: { enabled: true },
+            triage: { enabled: true, applyMode: "queue" },
+        },
+        sync: { enabled: true, push: true },
+    },
+    "memory-focus": {
+        description: "Memory and lesson improvement only — no distill or consolidate.",
+        processes: {
+            reflect: { enabled: true, allowedTypes: ["memory", "lesson"] },
+            distill: { enabled: false },
+            consolidate: { enabled: false },
+            memoryInference: { enabled: true },
+            graphExtraction: { enabled: false },
+            triage: { enabled: false },
+        },
+        // Limited pass opts out of end-of-run sync for the same reason as `quick`:
+        // a memory/lesson-only run should not auto-commit/push the stash. Explicit
+        // here because improve.ts treats an absent sync block as ENABLED + push.
+        sync: { enabled: false },
+    },
+};
+/**
+ * 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;
+}

package/dist/commands/improve-result-file.js

@@ -0,0 +1,167 @@
+// 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/.
+/**
+ * Helpers for persisting the `akm improve` result envelope.
+ *
+ * v0.8.0 behavioural default change:
+ *   - Default: the full result is recorded as a single row in the
+ *     `improve_runs` table of `state.db` (migration 003). Stdout is empty.
+ *     The existing `[improve] ...` progress log lines on stderr remain the
+ *     canonical console UX.
+ *   - `--json-to-stdout` restores the prior behaviour: full JSON to stdout,
+ *     nothing written to state.db.
+ *
+ * v0.8.0 storage change (this module): the previous on-disk artifact at
+ * `<stash>/.akm/runs/<runId>/improve-result.json` is no longer written. The
+ * canonical record now lives in `improve_runs` (see
+ * `src/core/state-db.ts`). Pre-existing files from older runs are not
+ * deleted by this change — they become historical artifacts. Zero current
+ * code paths read them, so no consumers needed to update.
+ *
+ * Run-id format: ISO-8601 timestamp (colons/dots replaced by `-`) plus an
+ * 8-char hex random suffix. There is no existing canonical run-id helper for
+ * persistent per-command artefacts on disk — the `workflow_runs` table uses
+ * `randomUUID()` but is database-scoped, and `consolidate-journal.json` is a
+ * single-slot artefact. We mint a fresh timestamped id for each improve run.
+ */
+import crypto from "node:crypto";
+import path from "node:path";
+import { openStateDatabase, recordImproveRun } from "../core/state-db";
+/**
+ * Build a stable run-id for a single improve invocation.
+ *
+ * Shape: `<iso-8601-utc-with-dashes>-<8 hex chars>`, e.g.
+ *   `2026-05-19T17-30-22-123Z-a1b2c3d4`.
+ *
+ * The hex suffix protects against same-millisecond collisions when multiple
+ * runs happen back-to-back in tests or scripts.
+ */
+export function buildImproveRunId(now = new Date()) {
+    const iso = now.toISOString().replace(/[:.]/g, "-");
+    const rand = crypto.randomBytes(4).toString("hex");
+    return `${iso}-${rand}`;
+}
+/**
+ * Return a stable, human-recognisable reference for a given improve run.
+ *
+ * Historical compatibility shim: callers used to receive a stash-relative
+ * file path like `.akm/runs/<runId>/improve-result.json`. With the state.db
+ * migration, no such file exists, but several callers still log "wrote to
+ * <path>" style messages. Returning a `state.db//improve_runs/<runId>`
+ * locator preserves the "the result is at <thing>" signature so existing
+ * log lines and error messages continue to make sense without rewriting
+ * every call site.
+ */
+export function relativeImproveResultPath(runId) {
+    return path.join("state.db", "improve_runs", runId);
+}
+/**
+ * Persist the full improve result into the `improve_runs` table of state.db.
+ *
+ * Backwards-compatible signature: the function name, argument list, and
+ * return type all match the pre-0.8.0 file-writing helper. The returned
+ * string is the `state.db//improve_runs/<runId>` locator (see
+ * {@link relativeImproveResultPath}), which is intended for log messages
+ * only — no caller should treat it as a filesystem path. Zero current
+ * readers existed for the previous file path, so this is a pure storage
+ * swap.
+ *
+ * The state.db row carries the scope and dry-run flag from `result.scope`
+ * and `result.dryRun`, plus the full result JSON for full fidelity. The
+ * dry-run column is indexed so productivity audits can filter cleanly
+ * (closes the dry-run/real-run artifact-trap recorded in MEMORY.md
+ * `feedback_akm_dryrun_artifact_trap`).
+ */
+export function writeImproveResultFile(stashDir, runId, result) {
+    const db = openStateDatabase();
+    try {
+        const startedAt = new Date().toISOString();
+        recordImproveRun(db, {
+            id: runId,
+            startedAt,
+            completedAt: startedAt,
+            stashDir,
+            dryRun: Boolean(result.dryRun),
+            profile: null,
+            scopeMode: result.scope?.mode ?? "all",
+            scopeValue: result.scope?.value ?? null,
+            guidance: result.guidance ?? null,
+            ok: Boolean(result.ok),
+            result,
+        });
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch {
+            // best-effort
+        }
+    }
+    return relativeImproveResultPath(runId);
+}
+/**
+ * Persist an improve_runs row for a run that did NOT complete normally.
+ * 2026-05-26 incident: the cron's `timeout_ms: 1800000` SIGTERM'd an
+ * akm-improve invocation at 30:00 with 54 actionable refs in-flight. No
+ * `improve_runs` row was written because the writer only fired at successful
+ * end-of-run, so the run vanished from `akm health --detail per-run` even
+ * though it had consumed 30 min of LLM time and produced 29 ref-level
+ * proposals. This helper closes that gap: signal handlers and the CLI
+ * try/catch wrapper call it on the abnormal-exit paths so the row exists
+ * with `ok: false` and `metadata.terminated.reason` set.
+ *
+ * The persisted result envelope is minimal — we don't try to reconstruct
+ * the in-flight `actions[]` because that state lives inside `akmImprove`
+ * and is gone by the time the signal handler runs. The row captures
+ * enough to know: a run started, was scoped to X, did NOT complete, and
+ * why.
+ */
+export function recordTerminatedImproveRun(stashDir, runId, startedAt, reason, ctx) {
+    const completedAt = new Date().toISOString();
+    const minimalResult = {
+        schemaVersion: 1,
+        ok: false,
+        scope: { mode: ctx?.scopeMode ?? "all", ...(ctx?.scopeValue ? { value: ctx.scopeValue } : {}) },
+        dryRun: Boolean(ctx?.dryRun),
+        actions: [],
+        plannedRefs: [],
+        terminated: {
+            reason,
+            at: completedAt,
+            ...(ctx?.errorMessage ? { errorMessage: ctx.errorMessage } : {}),
+        },
+    };
+    const db = openStateDatabase();
+    try {
+        recordImproveRun(db, {
+            id: runId,
+            startedAt,
+            completedAt,
+            stashDir,
+            dryRun: Boolean(ctx?.dryRun),
+            profile: ctx?.profile ?? null,
+            scopeMode: ctx?.scopeMode ?? "all",
+            scopeValue: ctx?.scopeValue ?? null,
+            guidance: null,
+            ok: false,
+            result: minimalResult,
+            metadata: {
+                terminated: {
+                    reason,
+                    at: completedAt,
+                    ...(ctx?.errorMessage ? { errorMessage: ctx.errorMessage } : {}),
+                },
+            },
+        });
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch {
+            // best-effort
+        }
+    }
+}