akm-cli 0.9.0-beta.6 → 0.9.0-rc.0

package/dist/commands/health/llm-usage.js

@@ -0,0 +1,65 @@
+// 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/.
+/**
+ * Aggregate `llm_usage` events (#576) into the window total + per-stage
+ * breakdown reported by `akm health`.
+ */
+import { readEvents } from "../../core/events.js";
+import { LLM_USAGE_EVENT } from "../../llm/usage-persist.js";
+import { toFiniteNumber } from "./improve-metrics.js";
+/** Stage key used for `llm_usage` events recorded outside any stage scope. */
+const UNATTRIBUTED_STAGE = "unattributed";
+function emptyLlmUsageStageAggregate() {
+    return {
+        calls: 0,
+        totalDurationMs: 0,
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+        reasoningTokens: 0,
+    };
+}
+function emptyLlmUsageAggregate() {
+    return { ...emptyLlmUsageStageAggregate(), byStage: {} };
+}
+/**
+ * Aggregate `llm_usage` events (#576) into a window total plus a per-stage
+ * breakdown of call count, wall-time, and token usage. Token fields absent from
+ * a best-effort record contribute 0. Calls with no `stage` land under
+ * {@link UNATTRIBUTED_STAGE}.
+ */
+export function summarizeLlmUsage(events) {
+    const aggregate = emptyLlmUsageAggregate();
+    for (const event of events) {
+        const meta = event.metadata ?? {};
+        const stageKey = typeof meta.stage === "string" && meta.stage ? meta.stage : UNATTRIBUTED_STAGE;
+        let stage = aggregate.byStage[stageKey];
+        if (!stage) {
+            stage = emptyLlmUsageStageAggregate();
+            aggregate.byStage[stageKey] = stage;
+        }
+        const durationMs = toFiniteNumber(meta.durationMs);
+        const promptTokens = toFiniteNumber(meta.promptTokens);
+        const completionTokens = toFiniteNumber(meta.completionTokens);
+        const totalTokens = toFiniteNumber(meta.totalTokens);
+        const reasoningTokens = toFiniteNumber(meta.reasoningTokens);
+        for (const target of [aggregate, stage]) {
+            target.calls += 1;
+            target.totalDurationMs += durationMs;
+            target.promptTokens += promptTokens;
+            target.completionTokens += completionTokens;
+            target.totalTokens += totalTokens;
+            target.reasoningTokens += reasoningTokens;
+        }
+    }
+    return aggregate;
+}
+export function readLlmUsageAggregate(stateDbPath, since, until) {
+    const events = readEvents({ since, type: LLM_USAGE_EVENT }, { dbPath: stateDbPath }).events.filter((event) => {
+        if (until === undefined)
+            return true;
+        return new Date(event.ts ?? since).getTime() < new Date(until).getTime();
+    });
+    return summarizeLlmUsage(events);
+}

package/dist/commands/health/md-report.js

@@ -0,0 +1,103 @@
+// 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 { INTERESTING_DELTA_PATHS, readNumericPath } from "./windows.js";
+function padRight(s, width) {
+    return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+function renderTable(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
+    const lines = [];
+    lines.push(headers.map((h, i) => padRight(h, widths[i] ?? 0)).join("  "));
+    for (const row of rows) {
+        lines.push(row.map((cell, i) => padRight(cell ?? "", widths[i] ?? 0)).join("  "));
+    }
+    return lines.join("\n");
+}
+/**
+ * Render `--detail per-run` rows as a TSV-ish aligned table. The column
+ * shape was originally inherited from the retired
+ * `scripts/improve-stats/runs-detail` bash helper; keep the same shape
+ * so operator muscle memory carries over.
+ *
+ * Columns: ts | ok | actions | refl_ok/fail/cd/skip |
+ *   distill_q/llm-fail/qrej/cfg/skip | cons_proc/promo/merge/del |
+ *   mem_cons/written/skip | graph_f/e/r | orphans | lint_f/fl
+ */
+export function renderRunsDetailMd(runs) {
+    const headers = [
+        "ts",
+        "ok",
+        "actions",
+        "refl_ok/fail/cd/skip",
+        "distill_q/llm-fail/qrej/cfg/skip",
+        "cons_proc/promo/merge/del",
+        "mem_cons/written/skip",
+        "graph_f/e/r",
+        "orphans",
+        "lint_f/fl",
+    ];
+    const rows = runs.map((r) => {
+        const totalActions = r.actions.reflect.ok +
+            r.actions.reflect.failed +
+            r.actions.reflect.cooldown +
+            r.actions.reflect.skipped +
+            r.actions.distill.queued +
+            r.actions.distill.llmFailed +
+            r.actions.distill.qualityRejected +
+            r.actions.distill.configDisabled +
+            r.actions.distill.skipped +
+            r.actions.memoryPrune +
+            r.actions.memoryInference +
+            r.actions.graphExtraction +
+            r.actions.error;
+        return [
+            r.startedAt,
+            String(r.ok),
+            String(totalActions),
+            `${r.actions.reflect.ok}/${r.actions.reflect.failed}/${r.actions.reflect.cooldown}/${r.actions.reflect.skipped}`,
+            `${r.actions.distill.queued}/${r.actions.distill.llmFailed}/${r.actions.distill.qualityRejected}/${r.actions.distill.configDisabled}/${r.actions.distill.skipped}`,
+            `${r.consolidation.processed}/${r.consolidation.promoted}/${r.consolidation.merged}/${r.consolidation.deleted}`,
+            `${r.memoryInference.considered}/${r.memoryInference.written}/${r.memoryInference.skippedNoFacts}`,
+            `${r.graphExtraction.extractedFiles}/${r.graphExtraction.entities}/${r.graphExtraction.relations}`,
+            String(r.orphansPurged),
+            `${r.lintFixed}/${r.lintFlagged}`,
+        ];
+    });
+    return renderTable(headers, rows);
+}
+/**
+ * Render a window-compare comparison as a side-by-side metric table with a
+ * delta column. Bad-direction deltas (e.g. +pct on failed counts) get a `!`
+ * marker prefix.
+ */
+export function renderWindowCompareMd(windows, deltas) {
+    if (windows.length === 0)
+        return "";
+    const headers = ["metric", ...windows.map((w) => w.name), "delta"];
+    const badIfPositive = new Set([
+        "improve.actions.reflect.failed",
+        "improve.actions.distill.llmFailed",
+        "improve.graphExtraction.failures",
+        "improve.graphExtraction.nonArrayBatchFailures",
+        "improve.wallTime.medianMs",
+        "improve.wallTime.p95Ms",
+        "improve.memoryInference.skippedNoFacts",
+    ]);
+    const rows = [];
+    for (const path of INTERESTING_DELTA_PATHS) {
+        const values = windows.map((w) => String(readNumericPath(w, path)));
+        const delta = deltas?.[path];
+        let deltaStr = "—";
+        if (delta) {
+            const pct = delta.pctChange;
+            const num = typeof pct === "number" ? pct : pct;
+            const sign = typeof num === "number" && num > 0 ? "+" : "";
+            const formatted = typeof num === "number" ? `${sign}${num}%` : String(num);
+            const marker = badIfPositive.has(path) && typeof num === "number" && num > 0 ? "!" : "";
+            deltaStr = marker + formatted;
+        }
+        rows.push([path, ...values, deltaStr]);
+    }
+    return renderTable(headers, rows);
+}

package/dist/commands/health/metrics.js

@@ -0,0 +1,278 @@
+// 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/.
+/**
+ * State.db-backed health metrics for `akm health`: the round-trip probe,
+ * auto-accept calibration, denominator-fixed coverage, the enrichment-vs-
+ * minting rollup, and the WS-5 per-run degradation metrics.
+ */
+import { appendEvent, readEvents } from "../../core/events.js";
+import { queryImproveRuns } from "../../storage/repositories/improve-runs-repository.js";
+import { listProposalGateDecisions, listStateProposals } from "../../storage/repositories/proposals-repository.js";
+import { gateDecisionsToSamples, summarizeCalibration } from "../improve/calibration.js";
+import { roundRate, toFiniteNumber } from "./improve-metrics.js";
+import { ENRICHMENT_LANES, } from "./types.js";
+/** Event type appended + read back by the state.db round-trip probe. */
+const HEALTH_PROBE_EVENT = "health_probe";
+export function probeStateDbRoundTrip(stateDbPath) {
+    const before = readEvents({}, { dbPath: stateDbPath }).nextOffset;
+    const started = Date.now();
+    appendEvent({ eventType: HEALTH_PROBE_EVENT, ref: "health:probe", metadata: { source: "akm health" } }, { dbPath: stateDbPath });
+    const after = readEvents({ sinceOffset: before, type: HEALTH_PROBE_EVENT, ref: "health:probe" }, { dbPath: stateDbPath });
+    const durationMs = Date.now() - started;
+    if (after.events.length === 0 || after.nextOffset <= before) {
+        return { ok: false, durationMs, error: "probe event was not readable after append" };
+    }
+    return { ok: true, durationMs };
+}
+/**
+ * Read the auto-accept gate calibration summary (#612) over `[since, until)`.
+ * Reads every proposal's `gateDecision` from the open state.db, projects the
+ * acted-on (auto-accepted / auto-rejected) decisions into calibration samples
+ * within the window, and aggregates them deterministically.
+ */
+export function readCalibration(db, since, until) {
+    const decisions = listProposalGateDecisions(db);
+    const samples = gateDecisionsToSamples(decisions, { since, ...(until !== undefined ? { until } : {}) });
+    return summarizeCalibration(samples);
+}
+// ── WS-5 Observability helpers ───────────────────────────────────────────────
+/**
+ * Compute WS-5 denominator-fixed coverage metrics.
+ *
+ * `coverage = accepted_proposals / total_assets` (Part V §3).
+ * The denominator is the TOTAL stash size (not the moving eligible set) so
+ * more-inclusive WS-1 ranking cannot spuriously inflate coverage.
+ * `eligibleFraction = eligible_assets / total_assets` is reported separately.
+ *
+ * Proposals are counted only when their `updatedAt` falls within `[since, until)`
+ * so the rate is genuinely window-scoped (matching the JSDoc on the type).
+ *
+ * @param db - Open state.db connection.
+ * @param totalAssets - Total stash asset count (eligible + derived) from the
+ *   most recent run's memorySummary. 0 = denominator unknown, returns NaN rates.
+ * @param eligibleAssets - Eligible (non-derived) asset count from the most recent run.
+ * @param since - Window start (ISO-8601). Proposals accepted before this are excluded.
+ * @param until - Window end (ISO-8601, exclusive). Absent = open-ended (up to now).
+ * @param stashDir - Optional: scope accepted proposals to one stash. Absent = all stashes.
+ */
+export function computeDenominatorFixedCoverage(db, totalAssets, eligibleAssets, since, until, stashDir) {
+    let acceptedProposals = 0;
+    let distinctRefs = 0;
+    try {
+        const proposals = listStateProposals(db, {
+            status: "accepted",
+            ...(stashDir ? { stashDir } : {}),
+        }).filter((p) => {
+            const updatedAt = p.updatedAt ?? "";
+            if (updatedAt < since)
+                return false;
+            if (until !== undefined && updatedAt >= until)
+                return false;
+            return true;
+        });
+        acceptedProposals = proposals.length;
+        // Coverage counts DISTINCT refs: N accepted rewrites of one asset are
+        // churn, not coverage. The raw proposal count is kept alongside so the
+        // churn ratio (proposals ÷ distinct refs) stays visible.
+        distinctRefs = new Set(proposals.map((p) => p.ref)).size;
+    }
+    catch {
+        // Fail open: table may not exist on older installs.
+    }
+    const churnRatio = distinctRefs > 0 ? roundRate(acceptedProposals / distinctRefs) : Number.NaN;
+    if (totalAssets === 0) {
+        return {
+            rate: Number.NaN,
+            eligibleFraction: Number.NaN,
+            acceptedProposals,
+            distinctRefs,
+            churnRatio,
+            totalAssets: 0,
+        };
+    }
+    return {
+        rate: roundRate(distinctRefs / totalAssets),
+        eligibleFraction: roundRate(eligibleAssets / totalAssets),
+        acceptedProposals,
+        distinctRefs,
+        churnRatio,
+        totalAssets,
+    };
+}
+/**
+ * Compute the enrichment-vs-minting rollup over the window's accepted,
+ * lane-attributed proposals (reporting-only; see {@link EnrichmentMintingRollup}).
+ *
+ * SQL-side `json_extract` keeps the (potentially large) `backupContent` blobs
+ * out of process memory. Pre-Phase-6C rows without an `eligibilitySource`
+ * cannot be lane-classified and are excluded. Fails open (undefined) when the
+ * proposals table is absent.
+ */
+export function computeEnrichmentMintingRollup(db, since, until) {
+    try {
+        const rows = db
+            .prepare(`SELECT
+           json_extract(metadata_json, '$.eligibilitySource') AS lane,
+           CASE WHEN json_extract(metadata_json, '$.backupContent') IS NULL THEN 1 ELSE 0 END AS is_minted,
+           COUNT(*) AS cnt
+         FROM proposals
+         WHERE status = 'accepted'
+           AND updated_at >= ?
+           AND (? IS NULL OR updated_at < ?)
+           AND json_extract(metadata_json, '$.eligibilitySource') IS NOT NULL
+           AND json_extract(metadata_json, '$.eligibilitySource') != ''
+         GROUP BY lane, is_minted`)
+            .all(since, until ?? null, until ?? null);
+        if (rows.length === 0)
+            return undefined;
+        const byLane = {};
+        for (const row of rows) {
+            byLane[row.lane] ??= { minted: 0, updated: 0 };
+            const entry = byLane[row.lane];
+            if (row.is_minted === 1)
+                entry.minted += row.cnt;
+            else
+                entry.updated += row.cnt;
+        }
+        let minted = 0;
+        let updated = 0;
+        for (const lane of ENRICHMENT_LANES) {
+            const entry = byLane[lane];
+            if (!entry)
+                continue;
+            minted += entry.minted;
+            updated += entry.updated;
+        }
+        const decided = minted + updated;
+        return {
+            minted,
+            updated,
+            share: decided > 0 ? roundRate(minted / decided) : Number.NaN,
+            byLane,
+        };
+    }
+    catch {
+        // Fail open: proposals table may not exist on older installs.
+        return undefined;
+    }
+}
+/**
+ * Compute WS-5 per-run degradation metrics (Part V §4).
+ *
+ * Health VIEWS only — reads from state.db tables populated by prior improve
+ * runs. Gracefully returns partial data when tables are absent (pre-WS-1/2).
+ *
+ * @param db - Open state.db connection.
+ * @param since - Window start (ISO-8601).
+ * @param until - Window end (ISO-8601).
+ */
+export function computeDegradationMetrics(db, since, until) {
+    // (a) Corpus diversity — salience rank distribution of the top-100 assets.
+    // We use the Gini coefficient of retrieval_salience scores as an intra-corpus
+    // diversity proxy. A Gini close to 1 = highly concentrated (entrenched top
+    // assets), Gini near 0 = flat/diverse. This is a single-snapshot metric;
+    // consecutive-run centroid distance requires cross-run history not yet stored.
+    let corpusCentroidDistance = Number.NaN;
+    let entrenchmentFlagged;
+    let salienceUniformityFlagged;
+    try {
+        const rows = db
+            .prepare(`SELECT retrieval_salience FROM asset_salience
+         ORDER BY rank_score DESC LIMIT 100`)
+            .all();
+        if (rows.length >= 5) {
+            const vals = rows.map((r) => r.retrieval_salience).sort((a, b) => a - b);
+            const n = vals.length;
+            const sumAbsDiff = vals.reduce((acc, xi, i) => {
+                return acc + vals.slice(i + 1).reduce((a, xj) => a + Math.abs(xi - xj), 0);
+            }, 0);
+            const mean = vals.reduce((a, b) => a + b, 0) / n;
+            // Gini = (sum |xi - xj|) / (2 n^2 mean); 0 = perfect equality, 1 = perfect inequality.
+            const gini = mean > 0 ? sumAbsDiff / (2 * n * n * mean) : 0;
+            // Re-express as a diversity proxy in [0,1]: high gini = low diversity.
+            // corpusCentroidDistance approximation: gini is "distance from uniform".
+            // Note: retrieval_salience values are in [0,1], so the max achievable Gini
+            // with this formula is ~0.5 (when one asset dominates and others are near 0).
+            // Two-tailed: >0.35 flags entrenchment (robustly above the ~0.1 uniform
+            // baseline); <0.08 flags uniformity collapse — the distribution no longer
+            // discriminates between assets (live 2026-07 value 0.040 sat unflagged
+            // in this tail under the old one-tailed check).
+            corpusCentroidDistance = roundRate(gini);
+            entrenchmentFlagged = gini > 0.35;
+            salienceUniformityFlagged = gini < 0.08;
+        }
+    }
+    catch {
+        // Table not present (pre-WS-1 install) — leave NaN.
+    }
+    // (b) Merge fidelity — fraction of consolidate accepted proposals in the window
+    // whose ref also has a consolidate skip-reason of "contradict_target_missing"
+    // or an event indicating contradiction. Uses the improve_runs result_json
+    // consolidation.contradicted count as a proxy.
+    // Simple implementation: contradictionRate = total_contradicted / max(1, total_processed)
+    // sourced from the window's consolidation envelope.
+    // (The full "merge proposal → later contradiction" correlation requires cross-run
+    // history; this is the available proxy.)
+    let mergeFidelityContradictionRate = 0;
+    try {
+        const runs = queryImproveRuns(db, since, until);
+        let totalContradicted = 0;
+        let totalProcessed = 0;
+        for (const row of runs) {
+            try {
+                const result = JSON.parse(row.result_json);
+                const cons = result.consolidation;
+                if (cons) {
+                    totalContradicted += toFiniteNumber(cons.contradicted);
+                    totalProcessed += toFiniteNumber(cons.processed);
+                }
+            }
+            catch {
+                // Skip malformed rows.
+            }
+        }
+        if (totalProcessed > 0) {
+            mergeFidelityContradictionRate = roundRate(totalContradicted / totalProcessed);
+        }
+    }
+    catch {
+        // Fail open.
+    }
+    // (c) highGenerationFraction was DELETED (meta-review 05 DRIFT-3): it
+    // approximated "LLM-merge generations" from consecutive_no_ops — which counts
+    // the opposite condition (cycles where nothing was changed) — and its own
+    // in-code TODO admitted the proxy. Display-only, never actionable; removed
+    // rather than instrumented.
+    // (d) Oracle spot-check — up to 5 recently accepted proposals in the window.
+    const oracleSpotCheck = [];
+    try {
+        const accepted = listStateProposals(db, { status: "accepted" }).filter((p) => {
+            const updatedAt = p.updatedAt ?? "";
+            return updatedAt >= since && updatedAt < until;
+        });
+        // Sample up to 5: pick evenly spaced (not just the first 5).
+        const step = Math.max(1, Math.floor(accepted.length / 5));
+        for (let i = 0; i < accepted.length && oracleSpotCheck.length < 5; i += step) {
+            const p = accepted[i];
+            if (p) {
+                oracleSpotCheck.push({
+                    proposalId: p.id,
+                    ref: p.ref,
+                    source: p.source ?? "unknown",
+                    acceptedAt: p.updatedAt ?? p.createdAt ?? "",
+                });
+            }
+        }
+    }
+    catch {
+        // Fail open.
+    }
+    return {
+        corpusCentroidDistance,
+        entrenchmentFlagged,
+        salienceUniformityFlagged,
+        mergeFidelityContradictionRate,
+        oracleSpotCheck,
+    };
+}

package/dist/commands/health/stash-exposure.js

@@ -0,0 +1,46 @@
+// 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/.
+/**
+ * `stash-git-exposure` surfaces advisory for `akm health` (08-F1).
+ *
+ * Versioning the stash is a supported use case (private-remote backup), so a
+ * tracked `env/`/`secrets/` directory is NOT wrong by itself. The leak moment
+ * is when secret assets are git-TRACKED **and** a remote is configured — only
+ * then can a `git push` exfiltrate tokens/keys. Warn on exactly that
+ * combination; stay silent on the tracked-but-no-remote opt-in so the advisory
+ * catches the exposure without nagging the intentional backup.
+ */
+import { spawnSync } from "node:child_process";
+const realGit = (stashDir, args) => {
+    const result = spawnSync("git", ["-C", stashDir, ...args], { encoding: "utf8", timeout: 5_000 });
+    return { ok: result.status === 0, stdout: (result.stdout ?? "").trim() };
+};
+/**
+ * Build the `stash-git-exposure` advisory, or `undefined` when there is nothing
+ * to warn about (not a git repo, no tracked env/secret assets, or no remote).
+ */
+export function collectStashExposureAdvisory(stashDir, git = realGit) {
+    // Not a git work tree → nothing to expose.
+    if (!git(stashDir, ["rev-parse", "--is-inside-work-tree"]).ok)
+        return undefined;
+    const tracked = git(stashDir, ["ls-files", "--", "env", "secrets"]);
+    if (!tracked.ok || tracked.stdout.length === 0)
+        return undefined; // no secret assets tracked
+    const remotes = git(stashDir, ["remote"]);
+    if (!remotes.ok || remotes.stdout.length === 0)
+        return undefined; // no push target → no leak path
+    const trackedFiles = tracked.stdout.split("\n").filter(Boolean);
+    const preview = trackedFiles.slice(0, 5).join(", ") + (trackedFiles.length > 5 ? `, +${trackedFiles.length - 5} more` : "");
+    return {
+        name: "stash-git-exposure",
+        kind: "deterministic",
+        status: "warn",
+        confidence: "high",
+        message: `${trackedFiles.length} env/secret file(s) are git-tracked AND a remote is configured — ` +
+            `a 'git push' can leak tokens/keys (${preview}). ` +
+            "Run 'git rm --cached' on them (a .gitignore rule alone does NOT untrack already-tracked " +
+            "files) and then add env/+secrets/ to .gitignore to prevent recurrence (akm init scaffolds it).",
+        evidence: { trackedSecretFiles: trackedFiles },
+    };
+}