akm-cli 0.8.0-rc2 → 0.8.0

package/dist/commands/registry-cli.js

@@ -0,0 +1,150 @@
+// 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 { defineCommand } from "citty";
+import { parsePositiveIntFlag } from "../cli/parse-args";
+import { output, runWithJsonErrors } from "../cli/shared";
+import { DEFAULT_CONFIG, loadUserConfig, saveConfig } from "../core/config";
+import { UsageError } from "../core/errors";
+import { warn } from "../core/warn";
+import { getHyphenatedArg, getHyphenatedBoolean } from "../output/context";
+import { buildRegistryIndex, writeRegistryIndex } from "../registry/build-index";
+import { searchRegistry } from "./registry-search";
+export const registryCommand = defineCommand({
+    meta: { name: "registry", description: "Manage stash registries" },
+    subCommands: {
+        list: defineCommand({
+            meta: { name: "list", description: "List configured registries" },
+            run() {
+                return runWithJsonErrors(() => {
+                    const config = loadUserConfig();
+                    const registries = config.registries ?? DEFAULT_CONFIG.registries;
+                    output("registry-list", { registries });
+                });
+            },
+        }),
+        add: defineCommand({
+            meta: { name: "add", description: "Add a registry by URL" },
+            args: {
+                url: { type: "positional", description: "Registry index URL", required: true },
+                name: { type: "string", description: "Human-friendly name for the registry" },
+                provider: { type: "string", description: "Provider type (e.g. static-index, skills-sh)" },
+                options: { type: "string", description: 'Provider options as JSON (e.g. \'{"apiKey":"key"}\').' },
+                "allow-insecure": {
+                    type: "boolean",
+                    description: "Allow a plain HTTP registry URL (otherwise rejected)",
+                    default: false,
+                },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    if (!args.url.startsWith("http")) {
+                        throw new UsageError("Registry URL must start with http:// or https://");
+                    }
+                    if (args.url.startsWith("http://")) {
+                        const allowInsecure = getHyphenatedBoolean(args, "allow-insecure");
+                        if (!allowInsecure) {
+                            throw new UsageError("Registry URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious index. " +
+                                "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.");
+                        }
+                        warn("Warning: registry URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious index.");
+                    }
+                    const config = loadUserConfig();
+                    const registries = [...(config.registries ?? [])];
+                    // Deduplicate by URL
+                    if (registries.some((r) => r.url === args.url)) {
+                        output("registry-add", { registries, added: false, message: "Registry URL already configured" });
+                        return;
+                    }
+                    const entry = { url: args.url };
+                    if (args.name)
+                        entry.name = args.name;
+                    if (args.provider)
+                        entry.provider = args.provider;
+                    if (args.options) {
+                        try {
+                            entry.options = JSON.parse(args.options);
+                        }
+                        catch {
+                            throw new UsageError("--options must be valid JSON");
+                        }
+                    }
+                    registries.push(entry);
+                    saveConfig({ ...config, registries });
+                    output("registry-add", { registries, added: true });
+                });
+            },
+        }),
+        remove: defineCommand({
+            meta: { name: "remove", description: "Remove a registry by URL or name" },
+            args: {
+                target: { type: "positional", description: "Registry URL or name to remove", required: true },
+                yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
+            },
+            run({ args }) {
+                return runWithJsonErrors(async () => {
+                    const config = loadUserConfig();
+                    const registries = [...(config.registries ?? [])];
+                    const idx = registries.findIndex((r) => r.url === args.target || r.name === args.target);
+                    if (idx === -1) {
+                        output("registry-remove", { registries, removed: false, message: "No matching registry found" });
+                        return;
+                    }
+                    const { confirmDestructive } = await import("../cli/confirm.js");
+                    const confirmed = await confirmDestructive(`Remove registry "${args.target}"? This cannot be undone.`, {
+                        yes: args.yes === true,
+                    });
+                    if (!confirmed) {
+                        process.stderr.write("Aborted.\n");
+                        return;
+                    }
+                    const removed = registries.splice(idx, 1)[0];
+                    saveConfig({ ...config, registries });
+                    output("registry-remove", { registries, removed: true, entry: removed });
+                });
+            },
+        }),
+        search: defineCommand({
+            meta: { name: "search", description: "Search enabled registries for stashes" },
+            args: {
+                query: { type: "positional", description: "Search query", required: true },
+                limit: { type: "string", description: "Maximum number of results" },
+                assets: { type: "boolean", description: "Include asset-level search results", default: false },
+            },
+            async run({ args }) {
+                await runWithJsonErrors(async () => {
+                    const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
+                    const result = await searchRegistry(args.query, { limit: limitRaw, includeAssets: args.assets });
+                    output("registry-search", result);
+                });
+            },
+        }),
+        "build-index": defineCommand({
+            meta: { name: "build-index", description: "Build a v2 registry index from discovery and manual entries" },
+            args: {
+                out: { type: "string", description: "Output path for the generated index" },
+                manual: { type: "string", description: "Manual entries JSON file" },
+                "npm-registry": { type: "string", description: "Override npm registry base URL" },
+                "github-api": { type: "string", description: "Override GitHub API base URL" },
+            },
+            async run({ args }) {
+                await runWithJsonErrors(async () => {
+                    const result = await buildRegistryIndex({
+                        manualEntriesPath: args.manual,
+                        npmRegistryBase: getHyphenatedArg(args, "npm-registry"),
+                        githubApiBase: getHyphenatedArg(args, "github-api"),
+                    });
+                    const outPath = writeRegistryIndex(result.index, args.out);
+                    output("registry-build-index", {
+                        outPath,
+                        version: result.index.version,
+                        updatedAt: result.index.updatedAt,
+                        totalKits: result.counts.total,
+                        counts: result.counts,
+                        manualEntriesPath: result.paths.manualEntriesPath,
+                    });
+                });
+            },
+        }),
+    },
+});

package/dist/commands/registry-search.js

@@ -1,3 +1,6 @@
+// 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 { toErrorMessage } from "../core/common";
 import { DEFAULT_CONFIG } from "../core/config";
 import { warn } from "../core/warn";

package/dist/commands/remember-cli.js

@@ -0,0 +1,257 @@
+// 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 { defineCommand } from "citty";
+import { output, parseAllFlagValues, runWithJsonErrors } from "../cli/shared";
+import { UsageError } from "../core/errors";
+import { appendEvent } from "../core/events";
+import { inferAssetName, writeMarkdownAsset } from "./knowledge";
+import { buildMemoryFrontmatter, parseDuration, readMemoryContent, resolveRememberContentArg, runAutoHeuristics, runLlmEnrich, } from "./remember";
+import { akmSearch } from "./search";
+// ── Helper: similar memory search ────────────────────────────────────────────
+/**
+ * Best-effort top-3 similar memory search for `--show-similar`.
+ * Scoped to memory: type; excludes the just-written ref.
+ */
+async function fetchSimilarMemories(query, excludeRef) {
+    try {
+        const result = await akmSearch({ query, type: "memory", limit: 4 });
+        return (result.hits ?? [])
+            .filter((h) => "ref" in h && h.ref !== excludeRef)
+            .slice(0, 3)
+            .map((h) => ({ ref: h.ref, ...(h.name ? { title: h.name } : {}) }));
+    }
+    catch {
+        return [];
+    }
+}
+// ── Command definition ────────────────────────────────────────────────────────
+export const rememberCommand = defineCommand({
+    meta: {
+        name: "remember",
+        description: "Record a memory in the default stash",
+    },
+    args: {
+        content: {
+            type: "positional",
+            description: "Memory content. Omit to read markdown from stdin.",
+            required: false,
+        },
+        name: {
+            type: "string",
+            description: "Memory name (defaults to a slug from the content)",
+        },
+        force: {
+            type: "boolean",
+            description: "Overwrite an existing memory with the same name",
+            default: false,
+        },
+        description: {
+            type: "string",
+            description: "Short description written to frontmatter (persisted as the memory's description field)",
+        },
+        tag: {
+            type: "string",
+            description: "Tag to add to the memory (repeatable: --tag foo --tag bar)",
+        },
+        expires: {
+            type: "string",
+            description: "Expiry duration shorthand (e.g. 30d, 12h, 6m). Resolved to an ISO date.",
+        },
+        source: {
+            type: "string",
+            description: "Source reference (URL, asset ref, file path, or any free-form string)",
+        },
+        auto: {
+            type: "boolean",
+            description: "Apply heuristic tagging (code, subjective, source, observed_at) from the body",
+            default: false,
+        },
+        enrich: {
+            type: "boolean",
+            description: "Call the configured LLM to propose tags and description (requires LLM config)",
+            default: false,
+        },
+        target: {
+            type: "string",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
+        },
+        user: {
+            type: "string",
+            description: "Scope this memory to a user id (persisted as `scope_user` frontmatter)",
+        },
+        agent: {
+            type: "string",
+            description: "Scope this memory to an agent id (persisted as `scope_agent` frontmatter)",
+        },
+        run: {
+            type: "string",
+            description: "Scope this memory to a run id (persisted as `scope_run` frontmatter)",
+        },
+        channel: {
+            type: "string",
+            description: "Scope this memory to a channel name (persisted as `scope_channel` frontmatter)",
+        },
+        showSimilar: {
+            type: "boolean",
+            description: "Return top-3 similar existing memories in output (opt-in)",
+        },
+    },
+    async run({ args }) {
+        return runWithJsonErrors(async () => {
+            const body = readMemoryContent(resolveRememberContentArg(args.content));
+            // Determine if the user has requested any structured metadata mode.
+            // Collect all --tag occurrences directly from process.argv because citty
+            // only exposes the last value for repeated string flags.
+            const rawTags = parseAllFlagValues("--tag");
+            // Collect scope flags. Scope alone counts as structured metadata so we
+            // emit frontmatter, but it does NOT trigger the "tags required" check —
+            // memory + scope (no tags) is a valid combination for multi-tenant use.
+            const scopeFields = {};
+            if (typeof args.user === "string" && args.user.trim())
+                scopeFields.user = args.user.trim();
+            if (typeof args.agent === "string" && args.agent.trim())
+                scopeFields.agent = args.agent.trim();
+            if (typeof args.run === "string" && args.run.trim())
+                scopeFields.run = args.run.trim();
+            if (typeof args.channel === "string" && args.channel.trim())
+                scopeFields.channel = args.channel.trim();
+            const hasScope = Object.keys(scopeFields).length > 0;
+            const hasTagRequiringArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description;
+            const hasStructuredArgs = hasTagRequiringArgs || hasScope || args.auto;
+            if (!hasStructuredArgs) {
+                // Phase 1B / Rec 7: even the zero-flag hot-path emits
+                // `captureMode: hot` + `beliefState: asserted` so user-supplied
+                // memories outrank background-derived ones during ranking.
+                const frontmatterBlock = buildMemoryFrontmatter({
+                    captureMode: "hot",
+                    beliefState: "asserted",
+                });
+                const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
+                // Derive the asset slug from the body (not the frontmatter block);
+                // otherwise inferAssetName would key off the leading `---` delimiter.
+                const result = await writeMarkdownAsset({
+                    type: "memory",
+                    content: contentWithFrontmatter,
+                    name: args.name,
+                    fallbackPrefix: "memory",
+                    preferredName: inferAssetName(body, "memory"),
+                    force: args.force,
+                    target: args.target,
+                });
+                appendEvent({
+                    eventType: "remember",
+                    ref: result.ref,
+                    metadata: { path: result.path, force: args.force === true },
+                });
+                if (args.showSimilar) {
+                    const similar = await fetchSimilarMemories(body.slice(0, 500), result.ref);
+                    output("remember", { ok: true, ...result, similar });
+                }
+                else {
+                    output("remember", { ok: true, ...result });
+                }
+                return;
+            }
+            // ── Accumulate metadata from all three modes ──────────────────────────
+            // Start with CLI args (Mode 1: always)
+            const tags = [...rawTags];
+            // --description is persisted as-is; LLM enrichment may fill it if absent.
+            let description = args.description || undefined;
+            let source = args.source;
+            let observed_at;
+            let expires;
+            let subjective;
+            // Resolve --expires to an ISO date string
+            if (args.expires) {
+                const durationMs = parseDuration(args.expires);
+                const expiresDate = new Date(Date.now() + durationMs);
+                expires = expiresDate.toISOString().slice(0, 10);
+            }
+            // Mode 2: --auto heuristics
+            if (args.auto) {
+                const auto = runAutoHeuristics(body);
+                for (const t of auto.tags) {
+                    if (!tags.includes(t))
+                        tags.push(t);
+                }
+                if (!source && auto.source)
+                    source = auto.source;
+                if (!observed_at && auto.observed_at)
+                    observed_at = auto.observed_at;
+                if (!subjective && auto.subjective)
+                    subjective = auto.subjective;
+            }
+            // Mode 3: --enrich LLM (fail-soft)
+            if (args.enrich) {
+                const enriched = await runLlmEnrich(body);
+                for (const t of enriched.tags) {
+                    if (!tags.includes(t))
+                        tags.push(t);
+                }
+                if (!description && enriched.description)
+                    description = enriched.description;
+                if (!observed_at && enriched.observed_at)
+                    observed_at = enriched.observed_at;
+            }
+            // ── Required-field check (before any write) ───────────────────────────
+            // Tags remain required when the user explicitly asked for tag-bearing
+            // metadata (--tag / --enrich / --description / --source / --expires).
+            // `--auto` alone is allowed even when its heuristics derive zero tags.
+            // Scope-only writes (`akm remember "..." --user u1`) also skip this
+            // check — scope is independent metadata and a memory with only scope is
+            // valid.
+            const missing = [];
+            if (hasTagRequiringArgs && tags.length === 0)
+                missing.push("tags");
+            if (missing.length > 0) {
+                throw new UsageError(`Memory is missing required frontmatter field(s): ${missing.join(", ")}. ` +
+                    "Provide them via --tag <value>, --auto (heuristics), or --enrich (LLM).");
+            }
+            // ── Build frontmatter and write ───────────────────────────────────────
+            // Phase 1B / Rec 7: the hot-path CLI write always marks the memory as
+            // `captureMode: hot` and `beliefState: asserted`. Ranking applies a
+            // hot-capture boost so user-supplied memories outrank otherwise-equal
+            // background-derived ones.
+            const frontmatterBlock = buildMemoryFrontmatter({
+                description,
+                tags,
+                source,
+                observed_at,
+                expires,
+                subjective,
+                captureMode: "hot",
+                beliefState: "asserted",
+                ...(hasScope ? { scope: scopeFields } : {}),
+            });
+            const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
+            const result = await writeMarkdownAsset({
+                type: "memory",
+                content: contentWithFrontmatter,
+                name: args.name,
+                fallbackPrefix: "memory",
+                force: args.force,
+                target: args.target,
+            });
+            appendEvent({
+                eventType: "remember",
+                ref: result.ref,
+                metadata: {
+                    path: result.path,
+                    force: args.force === true,
+                    tagCount: tags.length,
+                    enriched: args.enrich === true,
+                    auto: args.auto === true,
+                    ...(hasScope ? { scope: scopeFields } : {}),
+                },
+            });
+            if (args.showSimilar) {
+                const similar = await fetchSimilarMemories((body ?? args.content ?? "").slice(0, 500), result.ref);
+                output("remember", { ok: true, ...result, similar });
+            }
+            else {
+                output("remember", { ok: true, ...result });
+            }
+        });
+    },
+});

package/dist/commands/remember.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Memory-specific helpers for `akm remember`.
  *
@@ -5,9 +8,9 @@
  * heuristic derivation, LLM enrichment) is testable in isolation and the
  * CLI entry point stays focused on argument parsing + output routing.
  */
-import { stringify as yamlStringify } from "yaml";
+import { serializeFrontmatter } from "../core/asset-serialize";
 import { toErrorMessage, tryReadStdinText } from "../core/common";
-import { loadConfig } from "../core/config";
+import { getDefaultLlmConfig, loadConfig } from "../core/config";
 import { UsageError } from "../core/errors";
 import { warn } from "../core/warn";
 import { SCOPE_KEYS } from "../indexer/metadata";
@@ -54,6 +57,12 @@ export function buildMemoryFrontmatter(fields) {
         obj.expires = fields.expires;
     if (fields.subjective)
         obj.subjective = true;
+    if (fields.captureMode === "hot" || fields.captureMode === "background") {
+        obj.captureMode = fields.captureMode;
+    }
+    if (typeof fields.beliefState === "string" && fields.beliefState.trim()) {
+        obj.beliefState = fields.beliefState.trim();
+    }
     // Scope keys are emitted as flat top-level keys (`scope_user`, …) so the
     // existing one-level frontmatter parser can read them without nesting.
     // A scope object with no populated values is dropped.
@@ -69,7 +78,7 @@ export function buildMemoryFrontmatter(fields) {
     // produce `---\n{}\n---` (the YAML serializer's empty-object form).
     if (Object.keys(obj).length === 0)
         return "---\n---";
-    const serialized = yamlStringify(obj).trimEnd();
+    const serialized = serializeFrontmatter(obj);
     return `---\n${serialized}\n---`;
 }
 /**
@@ -134,11 +143,11 @@ const LLM_ENRICH_TIMEOUT_MS = 10_000;
  */
 export async function runLlmEnrich(body) {
     const config = loadConfig();
-    if (!config.llm) {
-        warn("Warning: --enrich requires an LLM to be configured. Run `akm config set llm` to configure one.");
+    const llmConfig = getDefaultLlmConfig(config);
+    if (!llmConfig) {
+        warn("Warning: --enrich requires an LLM to be configured. Run `akm setup` to configure one.");
         return { tags: [] };
     }
-    const llmConfig = config.llm;
     const { chatCompletion, parseEmbeddedJsonResponse: parseJsonResponse } = await import("../llm/client");
     const prompt = `You are a memory tagger for a developer knowledge base.
 Given the memory text below, return ONLY a JSON object with these fields:

package/dist/commands/schema-repair.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Schema-repair pass for `akm improve`.
  *
@@ -10,16 +13,27 @@
  * `chatCompletion`.
  */
 import fs from "node:fs";
-import { stringify as yamlStringify } from "yaml";
+import path from "node:path";
 import { parseAssetRef } from "../core/asset-ref";
+import { assembleAsset } from "../core/asset-serialize";
 import { appendEvent, readEvents } from "../core/events";
 import { parseFrontmatter } from "../core/frontmatter";
-import { info } from "../core/warn";
+import { createProposal, isProposalSkipped } from "../core/proposals";
+import { info, warn } from "../core/warn";
 import { resolveAssetPath } from "../indexer/path-resolver";
 import { chatCompletion, parseEmbeddedJsonResponse } from "../llm/client";
 // ── Constants ────────────────────────────────────────────────────────────────
 /** Minimum gap between schema-repair attempts on the same asset. */
 const SCHEMA_REPAIR_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+/**
+ * Per-ref attempt cap (O-6 / #379): maximum number of schema-repair attempts
+ * allowed within SCHEMA_REPAIR_WINDOW_MS. Prevents indefinite nightly re-repair
+ * of assets whose source content is genuinely ambiguous or inconsistently
+ * structured. After cap, the asset is skipped until the window rolls over.
+ * Self-Refine arXiv:2303.17651 — iteration must be bounded.
+ */
+const SCHEMA_REPAIR_MAX_ATTEMPTS = 3;
+const SCHEMA_REPAIR_WINDOW_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
 // ── Main ─────────────────────────────────────────────────────────────────────
 /**
  * Run the schema-repair loop for a batch of validation failures.
@@ -29,7 +43,7 @@ const SCHEMA_REPAIR_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 export async function runSchemaRepairPass(failures, options) {
     const repairs = [];
     const repairedRefs = new Set();
-    const { startMs, budgetMs, llmConfig, stashDir, findFilePath = defaultFindFilePath, isLessonCandidateFn = defaultIsLessonCandidate, } = options;
+    const { startMs, budgetMs, llmConfig, stashDir, findFilePath = defaultFindFilePath, isLessonCandidateFn = defaultIsLessonCandidate, chatFn = chatCompletion, } = options;
     for (const failure of failures) {
         if (Date.now() - startMs >= budgetMs)
             break;
@@ -42,11 +56,29 @@ export async function runSchemaRepairPass(failures, options) {
             repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
             continue;
         }
+        // O-6 / #379: Cap total attempts at SCHEMA_REPAIR_MAX_ATTEMPTS per SCHEMA_REPAIR_WINDOW_MS.
+        // Prevents indefinite nightly re-repair of assets whose source is genuinely ambiguous.
+        // After the cap is reached, the asset is skipped until the window rolls over.
+        const windowStart = Date.now() - SCHEMA_REPAIR_WINDOW_MS;
+        const attemptsInWindow = recentRepairs.events.filter((e) => e.ts !== undefined && new Date(e.ts).getTime() >= windowStart).length;
+        if (attemptsInWindow >= SCHEMA_REPAIR_MAX_ATTEMPTS) {
+            repairs.push({
+                ref: failure.ref,
+                reason: failure.reason,
+                outcome: "skipped",
+                error: `schema-repair attempt cap reached (${attemptsInWindow}/${SCHEMA_REPAIR_MAX_ATTEMPTS} in 30d window)`,
+            });
+            continue;
+        }
         const filePath = await findFilePath(failure.ref, stashDir);
         if (!filePath) {
             repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
             continue;
         }
+        if (path.extname(filePath).toLowerCase() !== ".md") {
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+            continue;
+        }
         try {
             const raw = fs.readFileSync(filePath, "utf8");
             const fm = parseFrontmatter(raw);
@@ -62,7 +94,7 @@ export async function runSchemaRepairPass(failures, options) {
             const fieldList = missingFields.join(" and ");
             info(`[improve] schema-repair ${failure.ref} (${fieldList})`);
             const bodyPreview = (fm.content ?? raw).slice(0, 2000);
-            const llmResponse = await chatCompletion(llmConfig, [
+            const llmResponse = await chatFn(llmConfig, [
                 {
                     role: "system",
                     content: `You generate concise asset frontmatter fields. Respond with a JSON object containing only the missing fields. No prose, no markdown fences.`,
@@ -87,17 +119,58 @@ export async function runSchemaRepairPass(failures, options) {
                 newFm.description = parsed.description;
             if (parsed.when_to_use)
                 newFm.when_to_use = parsed.when_to_use;
-            const fmStr = yamlStringify(newFm).trimEnd();
-            const newContent = `---\n${fmStr}\n---\n${fm.content}`;
-            fs.writeFileSync(filePath, newContent, "utf8");
-            info(`[improve] schema-repair written: ${failure.ref}`);
-            appendEvent({
-                eventType: "schema_repair_invoked",
-                ref: failure.ref,
-                metadata: { outcome: "written", reason: failure.reason },
-            });
-            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "written" });
-            repairedRefs.add(failure.ref);
+            const newContent = assembleAsset(newFm, fm.content);
+            // M-3 / #387: Route through proposal queue instead of writing directly to
+            // disk. This restores akm's safety invariant — the proposal queue is the
+            // only path to a committed asset write. LLM-generated `description` /
+            // `when_to_use` fields can be incorrect; routing through the queue makes
+            // them human-reviewable before they affect search ranking and curate hints.
+            // mem0 open gaps (arXiv:2504.19413) — any LLM write to a memory field
+            // should be human-reviewable.
+            if (stashDir) {
+                const proposalResult = createProposal(stashDir, {
+                    ref: failure.ref,
+                    source: "schema-repair",
+                    payload: {
+                        content: newContent,
+                        ...(Object.keys(newFm).length > 0 ? { frontmatter: newFm } : {}),
+                    },
+                });
+                if (isProposalSkipped(proposalResult)) {
+                    info(`[improve] schema-repair proposal skipped for ${failure.ref}: ${proposalResult.message}`);
+                    repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+                    continue;
+                }
+                info(`[improve] schema-repair queued: ${failure.ref} (proposal id: ${proposalResult.id})`);
+                appendEvent({
+                    eventType: "schema_repair_invoked",
+                    ref: failure.ref,
+                    metadata: { outcome: "queued", reason: failure.reason, proposalId: proposalResult.id },
+                });
+                repairs.push({
+                    ref: failure.ref,
+                    reason: failure.reason,
+                    outcome: "queued",
+                    proposalId: proposalResult.id,
+                });
+                // Mark as repaired so the caller removes it from the validation-failure set.
+                repairedRefs.add(failure.ref);
+            }
+            else {
+                // Fallback: no stash dir available — write directly (legacy path).
+                // This should not occur in production; stashDir is always provided by
+                // `runSchemaRepairPass` callers in improve.ts.
+                warn(`[improve] schema-repair: no stashDir available for ${failure.ref}, falling back to direct write`);
+                fs.writeFileSync(filePath, newContent, "utf8");
+                info(`[improve] schema-repair written: ${failure.ref}`);
+                appendEvent({
+                    eventType: "schema_repair_invoked",
+                    ref: failure.ref,
+                    metadata: { outcome: "written", reason: failure.reason },
+                });
+                repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "written" });
+                repairedRefs.add(failure.ref);
+            }
         }
         catch (e) {
             appendEvent({