akm-cli 0.9.0-beta.5 → 0.9.0-beta.51

package/dist/commands/improve/calibration.js

@@ -0,0 +1,161 @@
+// 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/.
+// ---------------------------------------------------------------------------
+// Reliability computation
+// ---------------------------------------------------------------------------
+/** Number of fixed-width reliability buckets over [0, 1]. */
+export const CALIBRATION_BUCKET_COUNT = 10;
+function roundRate(value) {
+    return Number(value.toFixed(4));
+}
+/**
+ * Assign a confidence in [0, 1] to one of {@link CALIBRATION_BUCKET_COUNT}
+ * fixed-width buckets. The final bucket is closed on the right so confidence
+ * === 1 lands in the top bucket rather than overflowing.
+ */
+function bucketIndex(confidence) {
+    const clamped = Math.min(1, Math.max(0, confidence));
+    const idx = Math.floor(clamped * CALIBRATION_BUCKET_COUNT);
+    return Math.min(CALIBRATION_BUCKET_COUNT - 1, idx);
+}
+/**
+ * Compute a deterministic calibration summary from a list of acted-on gate
+ * decisions. Pure: identical input always yields identical output, with no
+ * dependency on wall-clock time or randomness.
+ */
+export function summarizeCalibration(samples) {
+    const buckets = [];
+    const bucketCounts = new Array(CALIBRATION_BUCKET_COUNT).fill(0);
+    const bucketAccepted = new Array(CALIBRATION_BUCKET_COUNT).fill(0);
+    const bucketConfSum = new Array(CALIBRATION_BUCKET_COUNT).fill(0);
+    let accepted = 0;
+    let confSum = 0;
+    for (const sample of samples) {
+        const idx = bucketIndex(sample.confidence);
+        bucketCounts[idx] = (bucketCounts[idx] ?? 0) + 1;
+        bucketConfSum[idx] = (bucketConfSum[idx] ?? 0) + sample.confidence;
+        confSum += sample.confidence;
+        if (sample.outcome === "auto-accepted") {
+            accepted += 1;
+            bucketAccepted[idx] = (bucketAccepted[idx] ?? 0) + 1;
+        }
+    }
+    const total = samples.length;
+    const width = 1 / CALIBRATION_BUCKET_COUNT;
+    for (let i = 0; i < CALIBRATION_BUCKET_COUNT; i += 1) {
+        const count = bucketCounts[i] ?? 0;
+        const acc = bucketAccepted[i] ?? 0;
+        buckets.push({
+            lower: roundRate(i * width),
+            upper: roundRate((i + 1) * width),
+            count,
+            accepted: acc,
+            acceptRate: count > 0 ? roundRate(acc / count) : 0,
+            meanConfidence: count > 0 ? roundRate((bucketConfSum[i] ?? 0) / count) : 0,
+        });
+    }
+    const overallAcceptRate = total > 0 ? roundRate(accepted / total) : 0;
+    const meanConfidence = total > 0 ? roundRate(confSum / total) : 0;
+    return {
+        samples: total,
+        accepted,
+        rejected: total - accepted,
+        overallAcceptRate,
+        meanConfidence,
+        calibrationGap: total > 0 ? roundRate(meanConfidence - overallAcceptRate) : 0,
+        buckets,
+    };
+}
+/**
+ * Project a list of `gateDecision` records (read from the proposal store) into
+ * the acted-on calibration samples within an optional `[since, until)` window.
+ *
+ * Only `auto-accepted` / `auto-rejected` decisions with a finite confidence in
+ * [0, 1] contribute. `deferred` decisions and decisions missing a confidence
+ * are excluded (no realized accept/reject signal). The window filter uses each
+ * decision's `decidedAt` timestamp; decisions with an unparseable timestamp are
+ * kept only when no window is supplied.
+ *
+ * Exploration-budget promotions (`reason === "exploration-budget"`) are EXCLUDED:
+ * they are accepted regardless of confidence, so they carry no reliability signal
+ * about the gate threshold. Counting them would inflate the apparent accept-rate
+ * and bias the auto-tuner downward — they are exempt from auto-tune by design
+ * (WS-4 exploration budget).
+ */
+export function gateDecisionsToSamples(decisions, window) {
+    const sinceMs = window?.since ? new Date(window.since).getTime() : undefined;
+    const untilMs = window?.until ? new Date(window.until).getTime() : undefined;
+    const samples = [];
+    for (const decision of decisions) {
+        if (!decision)
+            continue;
+        if (decision.outcome !== "auto-accepted" && decision.outcome !== "auto-rejected")
+            continue;
+        if (decision.reason === "exploration-budget")
+            continue;
+        const confidence = decision.confidence;
+        if (typeof confidence !== "number" || !Number.isFinite(confidence) || confidence < 0 || confidence > 1)
+            continue;
+        if (sinceMs !== undefined || untilMs !== undefined) {
+            const ts = new Date(decision.decidedAt).getTime();
+            if (!Number.isFinite(ts))
+                continue;
+            if (sinceMs !== undefined && ts < sinceMs)
+                continue;
+            if (untilMs !== undefined && ts >= untilMs)
+                continue;
+        }
+        samples.push({ confidence, outcome: decision.outcome });
+    }
+    return samples;
+}
+/**
+ * Compute a bounded, opt-in threshold adjustment from a calibration summary.
+ * PURE and deterministic — does not mutate config or read the clock. The
+ * caller is responsible for persisting `newThreshold` and logging the result.
+ *
+ * Algorithm (deliberately simple and bounded):
+ *   - When `autoTune` is false → no-op (`disabled`).
+ *   - When samples < `minSamples` → no-op (`insufficient-samples`).
+ *   - Otherwise nudge by at most `maxStep` toward `targetAcceptRate`, then
+ *     clamp into `[minThreshold, maxThreshold]`. The step size scales with the
+ *     gap from target but is capped, so a single run can never make a large
+ *     swing.
+ */
+export function computeThresholdAutoTune(currentThreshold, summary, config) {
+    const previousThreshold = Math.round(currentThreshold);
+    const noop = (reason) => ({
+        adjusted: false,
+        previousThreshold,
+        newThreshold: previousThreshold,
+        delta: 0,
+        reason,
+    });
+    if (!config.autoTune)
+        return noop("disabled");
+    if (summary.samples < config.minSamples)
+        return noop("insufficient-samples");
+    const gap = config.targetAcceptRate - summary.overallAcceptRate;
+    // A small dead-band so tiny noise doesn't churn the threshold every run.
+    const DEAD_BAND = 0.01;
+    if (Math.abs(gap) <= DEAD_BAND)
+        return noop("within-target");
+    // gap > 0 ⇒ realized below target ⇒ raise threshold (be stricter).
+    // gap < 0 ⇒ realized above target ⇒ lower threshold (be more permissive).
+    const direction = gap > 0 ? 1 : -1;
+    // Scale the step with the gap magnitude (in points) but cap at maxStep.
+    const desiredMagnitude = Math.min(config.maxStep, Math.max(1, Math.round(Math.abs(gap) * 100)));
+    const proposed = previousThreshold + direction * desiredMagnitude;
+    const clamped = Math.min(config.maxThreshold, Math.max(config.minThreshold, proposed));
+    const delta = clamped - previousThreshold;
+    if (delta === 0)
+        return noop("clamped-at-bound");
+    return {
+        adjusted: true,
+        previousThreshold,
+        newThreshold: clamped,
+        delta,
+        reason: direction > 0 ? "below-target-raise" : "above-target-lower",
+    };
+}

package/dist/commands/improve/consolidate/chunking.js

@@ -0,0 +1,141 @@
+// 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/.
+// Chunk sizing + per-chunk prompt assembly for consolidate. Pure token math and
+// prompt-string construction over MemoryEntry inputs — no LLM call, no embedder,
+// no orchestrator coupling.
+import fs from "node:fs";
+import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { cacheHash } from "../dedup.js";
+/**
+ * Conservative chars-per-token estimate used when computing prompt budgets.
+ * English text averages roughly 4 chars/token for most LLM tokenizers. We use
+ * 3 to stay conservative (shorter tokens = more tokens per char).
+ */
+const CHARS_PER_TOKEN = 3;
+/**
+ * Overhead budget reserved for the system prompt, chunk header lines, and per-
+ * memory metadata lines (name, description, tags, separator). Measured at
+ * roughly 600 chars for the system prompt + ~100 chars of header + ~50 chars
+ * per memory × chunk size.  We round up to 2 000 tokens to leave room for the
+ * model's own output.
+ */
+const PROMPT_OVERHEAD_TOKENS = 2_000;
+/**
+ * Default effective token budget used when the default LLM profile's
+ * `contextLength` is not set. This is intentionally conservative (4 096)
+ * rather than being set to the model's actual context window, because:
+ *
+ *   - When the agent path is used, the agent CLI (e.g. opencode)
+ *     prepends its own large system prompt + conversation history before
+ *     forwarding to the model. That overhead easily consumes 30K+ tokens on
+ *     a model with a 16K context window, leaving very little room for
+ *     chunk content.
+ *   - When the HTTP path is used (an LLM profile is selected), only the akm
+ *     system prompt and user prompt are sent, so the budget can be set to the
+ *     model's actual context length via profiles.llm[defaults.llm].contextLength.
+ *
+ * Set profiles.llm[defaults.llm].contextLength in your config file to the
+ * model's actual context window to allow larger chunks on the HTTP path.
+ */
+export const DEFAULT_CONTEXT_LENGTH_TOKENS = 4_096;
+/**
+ * Given the model's context window and the per-memory body truncation limit,
+ * return the maximum number of memories that can safely fit in one chunk
+ * without the prompt overflowing the context window.
+ *
+ * The formula is:
+ *   usableTokens = contextLength - PROMPT_OVERHEAD_TOKENS
+ *   tokensPerMemory = ceil(bodyTruncation / CHARS_PER_TOKEN)
+ *   chunkSize = floor(usableTokens / tokensPerMemory)
+ *
+ * Result is clamped between 1 and 50 to avoid degenerate values.
+ *
+ * @param contextLength - Model context window in tokens.
+ * @param bodyTruncation - Max chars per memory body included in the prompt.
+ * @param maxChunkSize - Optional override for the hardcoded cap of 50 (1–50).
+ */
+export function computeSafeChunkSize(contextLength, bodyTruncation, maxChunkSize) {
+    const usableTokens = Math.max(contextLength - PROMPT_OVERHEAD_TOKENS, 0);
+    const tokensPerMemory = Math.max(Math.ceil(bodyTruncation / CHARS_PER_TOKEN), 1);
+    const raw = Math.floor(usableTokens / tokensPerMemory);
+    return Math.max(1, Math.min(maxChunkSize ?? 50, raw));
+}
+/**
+ * Build the per-chunk user prompt fed to the consolidate LLM.
+ *
+ * Each memory is annotated with two flags that drive the system-prompt
+ * rules at lines 181-186:
+ *   - `(captureMode: hot)` — user-explicit memory; system prompt rule 2
+ *     forbids proposing delete. ~60 wasted LLM verdicts/4h on this user's
+ *     stack before this annotation.
+ *   - `(already queued)` — the memory's body hash matches a pending
+ *     consolidate proposal; system prompt rule 3 forbids proposing
+ *     promote/merge/contradict. ~107/4h before this annotation.
+ *
+ * Both annotations are visible to the LLM. `pendingProposalBodyHashes`
+ * is precomputed once per run by `loadPendingConsolidateProposalHashes`
+ * so the cost stays O(memories) inside the chunk loop.
+ */
+export function buildChunkPrompt(sourceName, memories, chunkIndex, totalChunks, bodyTruncation, pendingProposalBodyHashes = new Set(), standardsContext = "") {
+    const start = memories[0] ? `memory:${memories[0].name}` : "";
+    const end = memories[memories.length - 1] ? `memory:${memories[memories.length - 1].name}` : "";
+    const annotationsByIndex = [];
+    const hotRefs = [];
+    for (const m of memories) {
+        let body = "";
+        try {
+            body = fs.readFileSync(m.filePath, "utf8");
+        }
+        catch {
+            body = "(unreadable)";
+        }
+        const parsed = parseFrontmatter(body);
+        const isHot = parsed.data.captureMode === "hot";
+        // Use cacheHash (case-preserving stripped body) to match the domain used
+        // by loadPendingConsolidateProposalHashes and the body-embedding cache.
+        const bodyHash = cacheHash(body);
+        const isAlreadyQueued = pendingProposalBodyHashes.has(bodyHash);
+        annotationsByIndex.push({ isHot, isAlreadyQueued, body });
+        if (isHot)
+            hotRefs.push(`memory:${m.name}`);
+    }
+    const lines = [
+        `Source: ${sourceName}`,
+        `Chunk ${chunkIndex + 1} of ${totalChunks}, memories ${start}–${end}:`,
+        "",
+    ];
+    if (standardsContext.trim()) {
+        lines.push("Standards to follow (the rulebook for this target):");
+        lines.push(standardsContext.trim());
+        lines.push("");
+    }
+    // Top-of-prompt protection block for hot refs. Neutral phrasing — avoid
+    // op-words like "promote", "merge", "contradict" so the model doesn't
+    // accidentally treat the warning as a hint to use that op elsewhere
+    // (variant B leaked the word "contradict" into the control sample
+    // during the diagnostic).
+    if (hotRefs.length > 0) {
+        lines.push("⛔ DO NOT propose any `delete` operation for these refs — they are user-explicit (captureMode: hot) and the downstream guard refuses them regardless. Proposing delete for any of these only wastes tokens.");
+        for (const ref of hotRefs)
+            lines.push(`  - ${ref}`);
+        lines.push("");
+    }
+    for (let i = 0; i < memories.length; i++) {
+        const m = memories[i];
+        const { isHot, isAlreadyQueued, body } = annotationsByIndex[i];
+        const annotations = [];
+        if (isHot)
+            annotations.push("captureMode: hot");
+        if (isAlreadyQueued)
+            annotations.push("already queued");
+        const annotationSuffix = annotations.length > 0 ? ` (${annotations.join("; ")})` : "";
+        lines.push(`[${i + 1}] memory:${m.name}${annotationSuffix}`);
+        lines.push(`Description: ${m.description || "(none)"}`);
+        lines.push(`Tags: ${m.tags.length > 0 ? m.tags.join(", ") : "(none)"}`);
+        lines.push("---");
+        lines.push(body.slice(0, bodyTruncation));
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/commands/improve/consolidate/eligibility.js

@@ -0,0 +1,81 @@
+// 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/.
+// Eligibility / safety predicates for consolidate: "may we touch this memory?"
+// One reason to change — the policy for what consolidate is allowed to act on.
+import fs from "node:fs";
+import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { hasHotCaptureMode } from "../../proposal/validators/proposal-quality-validators.js";
+export function isConsolidationEligibleMemoryName(name) {
+    return !name.endsWith(".derived");
+}
+/**
+ * #632 — AKM session-capture telemetry memories: auto-generated session-end
+ * checkpoints named `<harness>-session-<YYYYMMDD>-<id>` or
+ * `<harness>-checkpoint-<YYYYMMDD…>-<id>`, carrying an embedded
+ * `akm_memory_kind: session_checkpoint` metadata block. Their bodies are
+ * pipeline bookkeeping, not durable knowledge, so the improve passes exclude
+ * them from their pools (recombine, consolidate). The `\d{8}` datestamp anchor
+ * is what distinguishes a capture name from a durable memory that merely
+ * MENTIONS session/checkpoint (e.g. `akm-plugins-session-end-extract-hook`,
+ * `session-checkpoint-lint-skips`), which stay in the pool.
+ *
+ * Lives here (the eligibility module) rather than in recombine so both
+ * recombine and consolidate can reuse it without a circular import.
+ */
+export function isSessionCaptureMemoryName(name) {
+    return /-(session|checkpoint)-\d{8}/.test(name);
+}
+/**
+ * Returns true when the memory file has `captureMode: hot` in its frontmatter.
+ *
+ * Hot memories are USER-EXPLICIT (written via `akm remember` on the hot path).
+ * The consolidate LLM is forbidden from deleting or auto-merging them — the
+ * user wrote them on purpose and only the user can decide to retire them.
+ *
+ * Reads the file once per check; consolidate runs against ~10 memories per
+ * chunk so the IO cost is trivial. Returns false on any read/parse error
+ * (fail-safe: an unparseable file is treated as not-hot, but the broader
+ * consolidate flow already guards against unparseable memories elsewhere).
+ *
+ * Defends against four observed defect classes (see
+ * `memory:akm-improve-critical-review-2026-05-20`):
+ *   - LLM marks a memory contradicted then deletes (dangling contradictedBy)
+ *   - LLM merges two unrelated memories sharing a topic keyword
+ *   - LLM judges a recent durable design memo as "redundant"
+ *   - Cascade deletes (LLM uses ref:X as `contradictedBy` for ref:Y then deletes both)
+ */
+export function isHotCapturedMemory(filePath) {
+    try {
+        if (!fs.existsSync(filePath))
+            return false;
+        const content = fs.readFileSync(filePath, "utf8");
+        const parsed = parseFrontmatter(content);
+        return hasHotCaptureMode(parsed.data);
+    }
+    catch {
+        return false;
+    }
+}
+export function consolidateGuardStatus(filePath) {
+    if (!fs.existsSync(filePath))
+        return "missing";
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return "unparseable";
+    }
+    let parsed;
+    try {
+        parsed = parseFrontmatter(content);
+    }
+    catch {
+        return "unparseable";
+    }
+    const data = parsed.data;
+    if (!data || Object.keys(data).length === 0)
+        return "unparseable";
+    return hasHotCaptureMode(data) ? "hot" : "safe";
+}

package/dist/commands/improve/consolidate/merge.js

@@ -0,0 +1,145 @@
+// 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/.
+export function isValidOp(op) {
+    if (typeof op !== "object" || op === null)
+        return false;
+    const o = op;
+    if (o.op === "merge") {
+        return typeof o.primary === "string" && Array.isArray(o.secondaries);
+    }
+    if (o.op === "delete") {
+        return typeof o.ref === "string";
+    }
+    if (o.op === "promote") {
+        return typeof o.ref === "string" && typeof o.knowledgeRef === "string";
+    }
+    if (o.op === "contradict") {
+        return typeof o.ref === "string" && typeof o.contradictedByRef === "string";
+    }
+    return false;
+}
+export function mergePlans(chunks, knownRefs) {
+    const mergeOps = new Map();
+    const deleteOps = new Map();
+    const promoteOps = new Map();
+    // C-3 / #382: contradict ops keyed by `ref|contradictedByRef` to deduplicate.
+    const contradictOps = new Map();
+    const warnings = [];
+    for (const chunk of chunks) {
+        for (const op of chunk) {
+            if (op.op === "merge") {
+                // Drop ops whose primary the LLM hallucinated (not in the loaded memory
+                // pool). Without this guard, a hallucinated primary flows all the way to
+                // Phase B where !memoryByRef.has(primary) fires and charges every real
+                // secondary with merge_primary_missing — masking LLM hallucinations as
+                // filter regressions in health metrics.
+                if (knownRefs && !knownRefs.has(op.primary)) {
+                    warnings.push(`mergePlans: primary ${op.primary} not in loaded memory pool (LLM hallucination) — dropping op before execution.`);
+                    // Use a dedicated skip reason so dashboards can distinguish
+                    // hallucinated primaries from stale-DB regressions.
+                    // Secondaries are real refs; they are NOT charged here — they remain
+                    // available for other ops to claim.
+                    continue;
+                }
+                // Filter hallucinated secondaries while preserving real ones.
+                let mergeOp = op;
+                if (knownRefs) {
+                    const filteredSecondaries = op.secondaries.filter((sec) => {
+                        if (!knownRefs.has(sec)) {
+                            warnings.push(`mergePlans: secondary ${sec} not in loaded memory pool (LLM hallucination) — dropping from op.`);
+                            return false;
+                        }
+                        return true;
+                    });
+                    if (filteredSecondaries.length !== op.secondaries.length) {
+                        mergeOp = { ...op, secondaries: filteredSecondaries };
+                    }
+                }
+                // merge wins over delete
+                if (deleteOps.has(mergeOp.primary)) {
+                    deleteOps.delete(mergeOp.primary);
+                }
+                for (const sec of mergeOp.secondaries) {
+                    if (deleteOps.has(sec))
+                        deleteOps.delete(sec);
+                }
+                mergeOps.set(mergeOp.primary, mergeOp);
+            }
+            else if (op.op === "delete") {
+                // merge and promote both win over delete. A promote is non-destructive
+                // (creates a proposal) but the source memory is counted in `promoted`;
+                // if a delete also fires, the ref lands in both `promoted` and
+                // `skipReasons`, breaking the invariant by +1.
+                if (!mergeOps.has(op.ref) && !promoteOps.has(op.ref)) {
+                    deleteOps.set(op.ref, op);
+                }
+            }
+            else if (op.op === "promote") {
+                // C-2 / #381: when both a promote and a merge target the same ref,
+                // queue the promote FIRST rather than discarding it. The promote op
+                // routes through createProposal (the human-gated proposal queue), so
+                // it is non-destructive. The merge follows after the proposal is
+                // created. This preserves the human reviewer's ability to inspect the
+                // promotion before the source memory is merged/deleted.
+                // AGM K*8 — retain the maximally informative consistent subset.
+                promoteOps.set(op.ref, op);
+            }
+            else if (op.op === "contradict") {
+                // Deduplicate by ref+contradictedByRef pair.
+                const key = `${op.ref}|${op.contradictedByRef}`;
+                if (!contradictOps.has(key)) {
+                    contradictOps.set(key, op);
+                }
+            }
+        }
+    }
+    // Second pass: enforce merge-wins-over-delete and deduplicate secondaries.
+    //
+    // 1. Delete/secondary ordering bug: the per-chunk loop removes delete ops
+    //    for secondaries that were already in deleteOps, but misses the case
+    //    where the delete chunk came first. A full sweep here fixes both orders.
+    //
+    // 2. Cross-merge secondary dedup: if ref A is a secondary in two merge ops,
+    //    only the first (insertion-order) retains it. Without this, a successful
+    //    merge credits A to mergedSecondaries and a later merge's emitMerge-
+    //    FailureSkips also charges A to skipReasons — double-counting A while
+    //    processed has it only once.
+    //
+    // 3. Primary-as-secondary dedup: if ref A is a primary in one merge op and
+    //    a secondary in another, remove A from the secondary list. Both merges
+    //    would otherwise claim A (merged++ for A, then mergedSecondaries++ for A)
+    //    breaking the invariant the same way.
+    // Also remove delete ops for any ref claimed by a promote op (handles the
+    // case where the delete chunk appeared before the promote chunk).
+    for (const ref of promoteOps.keys()) {
+        deleteOps.delete(ref);
+    }
+    const claimedSecondaries = new Set();
+    for (const mergeOp of mergeOps.values()) {
+        deleteOps.delete(mergeOp.primary);
+        mergeOp.secondaries = mergeOp.secondaries.filter((sec) => {
+            if (mergeOps.has(sec)) {
+                warnings.push(`Merge: secondary ${sec} is also a merge primary — removing from secondary list to avoid double-count.`);
+                return false;
+            }
+            if (claimedSecondaries.has(sec)) {
+                warnings.push(`Merge: secondary ${sec} appears in multiple merge ops — retaining in first op only.`);
+                return false;
+            }
+            claimedSecondaries.add(sec);
+            deleteOps.delete(sec);
+            return true;
+        });
+    }
+    // C-2 / #381: promote ops are ordered BEFORE merge ops so that the
+    // human-gated proposal queue entry is created before any destructive merge.
+    // Phase B processes ops in array order, so promote executes first.
+    const ops = [
+        ...promoteOps.values(),
+        ...mergeOps.values(),
+        ...deleteOps.values(),
+        ...contradictOps.values(),
+    ];
+    return { ops, warnings };
+}