akm-cli 0.9.0-beta.54 → 0.9.0-beta.55

package/dist/commands/improve/procedural.js

@@ -24,17 +24,15 @@ import fs from "node:fs";
 import proceduralSystemPrompt from "../../assets/prompts/procedural-system.md" with { type: "text" };
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { resolveStashDir } from "../../core/common.js";
-import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
+import { loadConfig } from "../../core/config/config.js";
 import { appendEvent } from "../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
-import { warn } from "../../core/warn.js";
 import { closeDatabase, getAllEntries, openExistingDatabase } from "../../indexer/db/db.js";
-import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
-import { chatCompletion } from "../../llm/client.js";
 import { parseWorkflow } from "../../workflows/parser.js";
+import { createProposal, isProposalSkipped } from "../proposal/repository.js";
 import { validateProposalFrontmatter } from "../proposal/validators/proposal-quality-validators.js";
-import { createProposal, isProposalSkipped } from "../proposal/validators/proposals.js";
+import { resolveImproveLlmFn } from "./shared.js";
 const PROCEDURAL_SYSTEM_PROMPT = proceduralSystemPrompt;
 const DEFAULT_MIN_RECURRENCE = 3;
 const DEFAULT_MAX_PROPOSALS_PER_RUN = 3;
@@ -240,31 +238,6 @@ export function assembleWorkflowMarkdown(doc) {
     return lines.join("\n");
 }
 // ── Production LLM seam ───────────────────────────────────────────────────────
-/**
- * Resolve the production LLM seam from the active improve profile. Returns a
- * `ProceduralLlmFn` that issues one bounded chatCompletion per call, or
- * `undefined` when no LLM is configured (the pass then makes no calls).
- */
-function resolveProductionLlmFn(config, signal) {
-    const proceduralProcess = config.profiles?.improve?.default?.processes?.procedural;
-    const runnerSpec = resolveImproveProcessRunnerFromProfile(proceduralProcess, config);
-    const llmConfig = runnerSpec && runnerIsLlm(runnerSpec) ? runnerSpec.connection : getDefaultLlmConfig(config);
-    if (!llmConfig)
-        return undefined;
-    return async (prompt) => {
-        const messages = [
-            { role: "system", content: PROCEDURAL_SYSTEM_PROMPT },
-            { role: "user", content: prompt },
-        ];
-        try {
-            return await chatCompletion(llmConfig, messages, { signal, enableThinking: false });
-        }
-        catch (e) {
-            warn(`[procedural] LLM call failed: ${String(e)}`);
-            return null;
-        }
-    };
-}
 // ── Main entry point ───────────────────────────────────────────────────────────
 export async function akmProcedural(opts) {
     const startMs = Date.now();
@@ -313,7 +286,13 @@ export async function akmProcedural(opts) {
     if (clusters.length === 0) {
         return finish({ sequencesScanned, clustersFormed: 0 });
     }
-    const llmFn = opts.proceduralLlmFn ?? resolveProductionLlmFn(config, opts.signal);
+    const llmFn = opts.proceduralLlmFn ??
+        resolveImproveLlmFn(config, {
+            processKey: "procedural",
+            systemPrompt: PROCEDURAL_SYSTEM_PROMPT,
+            tag: "[procedural]",
+            signal: opts.signal,
+        });
     if (!llmFn) {
         warnings.push("procedural: no LLM configured — skipping");
         return finish({ sequencesScanned, clustersFormed: 0 });

package/dist/commands/improve/recombine.js

@@ -40,20 +40,20 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import recombineSystemPrompt from "../../assets/prompts/recombine-system.md" with { type: "text" };
+import { assembleAssetFromString } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { resolveStashDir } from "../../core/common.js";
-import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
+import { loadConfig } from "../../core/config/config.js";
 import { appendEvent } from "../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
-import { decayUnseenRecombineHypotheses, findMatchingRecombineHypothesis, getRecombineHypothesis, markRecombineHypothesisPromoted, recordRecombineInduction, withStateDbAsync, } from "../../core/state-db.js";
-import { warn } from "../../core/warn.js";
+import { withStateDbAsync } from "../../core/state-db.js";
 import { closeDatabase, getAllEntries, getEntitiesByEntryIds, openExistingDatabase, } from "../../indexer/db/db.js";
-import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
-import { chatCompletion } from "../../llm/client.js";
+import { decayUnseenRecombineHypotheses, findMatchingRecombineHypothesis, getRecombineHypothesis, markRecombineHypothesisPromoted, recordRecombineInduction, } from "../../storage/repositories/recombine-repository.js";
+import { archiveProposal, createProposal, isProposalSkipped, listProposals } from "../proposal/repository.js";
 import { isValidDescription, isValidWhenToUse, validateProposalFrontmatter, } from "../proposal/validators/proposal-quality-validators.js";
-import { archiveProposal, createProposal, isProposalSkipped, listProposals } from "../proposal/validators/proposals.js";
 import { isConsolidationEligibleMemoryName, isSessionCaptureMemoryName } from "./consolidate.js";
+import { resolveImproveLlmFn } from "./shared.js";
 const RECOMBINE_SYSTEM_PROMPT = recombineSystemPrompt;
 const DEFAULT_MIN_CLUSTER_SIZE = 3;
 const DEFAULT_MAX_CLUSTERS_PER_RUN = 5;
@@ -487,31 +487,6 @@ function parseGeneralization(raw) {
         return null;
     return { description, body, ...(when_to_use ? { when_to_use } : {}) };
 }
-/**
- * Resolve the production LLM seam from the active improve profile. Returns a
- * `RecombineLlmFn` that issues one bounded chatCompletion per call, or
- * `undefined` when no LLM is configured (the pass then makes no calls).
- */
-function resolveProductionLlmFn(config, signal) {
-    const recombineProcess = config.profiles?.improve?.default?.processes?.recombine;
-    const runnerSpec = resolveImproveProcessRunnerFromProfile(recombineProcess, config);
-    const llmConfig = runnerSpec && runnerIsLlm(runnerSpec) ? runnerSpec.connection : getDefaultLlmConfig(config);
-    if (!llmConfig)
-        return undefined;
-    return async (clusterPrompt) => {
-        const messages = [
-            { role: "system", content: RECOMBINE_SYSTEM_PROMPT },
-            { role: "user", content: clusterPrompt },
-        ];
-        try {
-            return await chatCompletion(llmConfig, messages, { signal, enableThinking: false });
-        }
-        catch (e) {
-            warn(`[recombine] LLM call failed: ${String(e)}`);
-            return null;
-        }
-    };
-}
 // ── Main entry point ───────────────────────────────────────────────────────────
 export async function akmRecombine(opts) {
     const startMs = Date.now();
@@ -581,7 +556,13 @@ export async function akmRecombine(opts) {
     let proposalsEmitted = 0;
     let lessonsPromoted = 0;
     let nullsReturned = 0;
-    const llmFn = opts.recombineLlmFn ?? resolveProductionLlmFn(config, opts.signal);
+    const llmFn = opts.recombineLlmFn ??
+        resolveImproveLlmFn(config, {
+            processKey: "recombine",
+            systemPrompt: RECOMBINE_SYSTEM_PROMPT,
+            tag: "[recombine]",
+            signal: opts.signal,
+        });
     if (!llmFn) {
         warnings.push("recombine: no LLM configured — skipping");
         return finish({ clustersFormed: 0 });
@@ -836,15 +817,10 @@ export async function akmRecombine(opts) {
 }
 /** Serialize frontmatter + body into a markdown asset string. */
 function assembleContent(frontmatter, body) {
-    const lines = ["---"];
-    for (const [key, value] of Object.entries(frontmatter)) {
-        if (Array.isArray(value)) {
-            lines.push(`${key}: [${value.map((v) => JSON.stringify(v)).join(", ")}]`);
-        }
-        else {
-            lines.push(`${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
-        }
-    }
-    lines.push("---", "", body, "");
-    return lines.join("\n");
+    const fmLines = Object.entries(frontmatter)
+        .map(([key, value]) => Array.isArray(value)
+        ? `${key}: [${value.map((v) => JSON.stringify(v)).join(", ")}]`
+        : `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`)
+        .join("\n");
+    return assembleAssetFromString(fmLines, body);
 }

package/dist/commands/improve/reflect.js

@@ -45,8 +45,8 @@ import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.
 import { chatCompletion } from "../../llm/client.js";
 import { isLlmFeatureEnabled } from "../../llm/feature-gate.js";
 import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigFromDisk, resolveAgentProfile, } from "../agent/agent-support.js";
+import { createProposal, isProposalSkipped, listProposals, } from "../proposal/repository.js";
 import { checkReflectSize, isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
-import { createProposal, isProposalSkipped, listProposals, } from "../proposal/validators/proposals.js";
 import { deriveLessonRef, runLessonQualityJudge } from "./distill.js";
 import { classifyReflectChange } from "./reflect-noise.js";
 const MAX_FEEDBACK_LINES = 10;

package/dist/commands/improve/schema-similarity-gate.js

@@ -0,0 +1,168 @@
+// 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/.
+/**
+ * WS-3b Step 0b — Schema-similarity intake gate.
+ *
+ * At intake, if a new candidate's body embedding is within ε of an existing
+ * derived-layer lesson/knowledge node, mark `schema-consistent` and lower its
+ * priority; only schema-inconsistent/contradicting candidates get full
+ * `encodingSalience`. One embedding lookup via body_embeddings cache; relieves
+ * dedup pressure before it accumulates.
+ *
+ * @module schema-similarity-gate
+ */
+import { warn } from "../../core/warn.js";
+import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
+/** Default epsilon for schema-similarity gate (looser than dedup's 0.97). */
+export const DEFAULT_SCHEMA_SIMILARITY_EPSILON = 0.85;
+/** Default multiplicative confidence penalty applied to schema-consistent candidates. */
+export const DEFAULT_SCHEMA_CONFIDENCE_PENALTY = 0.5;
+/**
+ * Check whether a candidate body embedding is schema-consistent with an existing
+ * derived-layer lesson/knowledge node. Returns `true` when the candidate is
+ * within ε of ANY existing derived node (i.e. it's likely covering ground the
+ * derived layer already knows about, so give it lower priority).
+ *
+ * One embedding lookup via the body_embeddings cache; no LLM call.
+ * Fails open: returns `false` (not schema-consistent) on any error so the
+ * candidate is not silently dropped.
+ *
+ * @param candidateEmbedding - Float32 embedding vector for the candidate body.
+ * @param existingDerivedEmbeddings - Pre-loaded embeddings for existing derived assets.
+ * @param config - Schema-similarity gate config.
+ */
+export function isSchemaConsistent(candidateEmbedding, existingDerivedEmbeddings, config) {
+    if (!config.enabled || existingDerivedEmbeddings.length === 0) {
+        return { consistent: false };
+    }
+    const epsilon = config.epsilon ?? DEFAULT_SCHEMA_SIMILARITY_EPSILON;
+    let bestSim = -Infinity;
+    let bestRef;
+    for (const { ref, embedding } of existingDerivedEmbeddings) {
+        // cosine similarity: dot(a,b) / (|a| * |b|)
+        let dot = 0;
+        let magA = 0;
+        let magB = 0;
+        for (let i = 0; i < candidateEmbedding.length; i++) {
+            const a = candidateEmbedding[i] ?? 0;
+            const b = embedding[i] ?? 0;
+            dot += a * b;
+            magA += a * a;
+            magB += b * b;
+        }
+        const sim = magA === 0 || magB === 0 ? 0 : dot / (Math.sqrt(magA) * Math.sqrt(magB));
+        if (sim > bestSim) {
+            bestSim = sim;
+            bestRef = ref;
+        }
+    }
+    if (bestSim >= epsilon) {
+        return { consistent: true, matchedRef: bestRef, similarity: bestSim };
+    }
+    return { consistent: false };
+}
+/**
+ * WS-3b Step-0b: apply the schema-similarity intake gate to one extract
+ * candidate. Pure/deterministic given `embedText`, so it is directly unit
+ * testable without the full extract→LLM harness.
+ *
+ * Returns the (possibly penalised) effective confidence plus a `penalised` flag
+ * and an optional human-readable `warning`. Parity guarantees:
+ *  - `ctx === null` (gate disabled / default-off)  → no change, never embeds.
+ *  - empty `derivedEmbeddings`                      → no change, never embeds.
+ *  - candidate type not lesson/knowledge            → no change, never embeds.
+ *  - embed throws                                   → fail open (no change), warns.
+ */
+export async function applySchemaSimilarityPenalty(candidate, ctx, embedText) {
+    const baseConfidence = typeof candidate.confidence === "number" ? candidate.confidence : undefined;
+    if (ctx === null || ctx.derivedEmbeddings.length === 0) {
+        return { effectiveConfidence: baseConfidence, penalised: false };
+    }
+    if (candidate.type !== "lesson" && candidate.type !== "knowledge") {
+        return { effectiveConfidence: baseConfidence, penalised: false };
+    }
+    try {
+        const candidateVec = await embedText(candidate.body);
+        const check = isSchemaConsistent(candidateVec, ctx.derivedEmbeddings, ctx.config);
+        if (check.consistent) {
+            const penalty = ctx.config.confidencePenalty ?? DEFAULT_SCHEMA_CONFIDENCE_PENALTY;
+            return {
+                effectiveConfidence: (baseConfidence ?? 1.0) * penalty,
+                penalised: true,
+                warning: `[extract] schema-consistent candidate ${candidate.type}:${candidate.name} ` +
+                    `(sim=${check.similarity?.toFixed(3)} vs ${check.matchedRef}) — confidence penalised ×${penalty}`,
+            };
+        }
+        return { effectiveConfidence: baseConfidence, penalised: false };
+    }
+    catch (embedErr) {
+        // Fail open: embed errors must never abort extraction.
+        return {
+            effectiveConfidence: baseConfidence,
+            penalised: false,
+            warning: `[extract] schema-similarity embed failed for ${candidate.type}:${candidate.name} — skipping gate: ` +
+                (embedErr instanceof Error ? embedErr.message : String(embedErr)),
+        };
+    }
+}
+/**
+ * Load persisted body embeddings for all indexed **derived-layer**
+ * (lesson + knowledge) entries from index.db. Returns an empty array when
+ * the DB is unavailable, empty, or the embeddings table has no entries for
+ * those types — the caller treats an empty array as "gate inactive".
+ *
+ * FAIL-OPEN: any error emits a debug warning and returns an empty array.
+ * This ensures the extract pass never fails because of a missing index.
+ *
+ * The returned entries are keyed by `entry_key` (e.g. "lesson:foo",
+ * "knowledge:bar"). Only entries whose embedding dimension matches the first
+ * observed dimension are included (mixed-dim BLOBs are silently skipped).
+ *
+ * @param dbPath - Optional path override for index.db (for testing).
+ */
+export function loadDerivedLayerEmbeddings(dbPath) {
+    let db;
+    try {
+        db = openExistingDatabase(dbPath);
+        const rows = db
+            .prepare(`SELECT e.entry_key, emb.embedding
+         FROM entries e
+         JOIN embeddings emb ON emb.id = e.id
+         WHERE e.entry_type IN ('lesson', 'knowledge')`)
+            .all();
+        if (rows.length === 0)
+            return [];
+        let expectedDim;
+        const result = [];
+        for (const row of rows) {
+            const buf = row.embedding;
+            if (!buf || buf.byteLength === 0 || buf.byteLength % 4 !== 0)
+                continue;
+            const dim = buf.byteLength / 4;
+            if (expectedDim === undefined)
+                expectedDim = dim;
+            if (dim !== expectedDim)
+                continue;
+            const aligned = new ArrayBuffer(buf.byteLength);
+            new Uint8Array(aligned).set(buf);
+            const f32 = new Float32Array(aligned);
+            result.push({ ref: row.entry_key, embedding: Array.from(f32) });
+        }
+        return result;
+    }
+    catch (err) {
+        warn("[schema-similarity-gate] loadDerivedLayerEmbeddings: failed to load from index.db — gate inactive:", err instanceof Error ? err.message : String(err));
+        return [];
+    }
+    finally {
+        if (db) {
+            try {
+                closeDatabase(db);
+            }
+            catch {
+                // ignore close errors
+            }
+        }
+    }
+}

package/dist/commands/improve/shared.js

@@ -0,0 +1,48 @@
+// 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 { getDefaultLlmConfig } from "../../core/config/config.js";
+import { warn } from "../../core/warn.js";
+import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
+import { chatCompletion } from "../../llm/client.js";
+/** Normalize an unknown thrown value to a human-readable message string. */
+export function errMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * Slugify an asset ref for use in eval-case / rejection filenames: lowercase,
+ * non-alphanumerics collapsed to `-`, capped at 60 characters.
+ */
+export function refSlug(ref) {
+    return ref
+        .replace(/[^a-z0-9]/gi, "-")
+        .toLowerCase()
+        .slice(0, 60);
+}
+/**
+ * Resolve the production LLM seam for an improve process (`recombine` /
+ * `procedural`) from the active default improve profile. Returns a function
+ * that issues one bounded chatCompletion per call, or `undefined` when no LLM
+ * is configured (the pass then makes no calls). Previously copied verbatim in
+ * recombine.ts and procedural.ts.
+ */
+export function resolveImproveLlmFn(config, opts) {
+    const processConfig = config.profiles?.improve?.default?.processes?.[opts.processKey];
+    const runnerSpec = resolveImproveProcessRunnerFromProfile(processConfig, config);
+    const llmConfig = runnerSpec && runnerIsLlm(runnerSpec) ? runnerSpec.connection : getDefaultLlmConfig(config);
+    if (!llmConfig)
+        return undefined;
+    return async (prompt) => {
+        const messages = [
+            { role: "system", content: opts.systemPrompt },
+            { role: "user", content: prompt },
+        ];
+        try {
+            return await chatCompletion(llmConfig, messages, { signal: opts.signal, enableThinking: false });
+        }
+        catch (e) {
+            warn(`${opts.tag} LLM call failed: ${String(e)}`);
+            return null;
+        }
+    };
+}

package/dist/commands/observability-cli.js

@@ -28,7 +28,7 @@ import { parsePositiveIntFlag } from "../cli/parse-args.js";
 import { defineJsonCommand, output, parseAllFlagValues, runWithJsonErrors } from "../cli/shared.js";
 import { closeDatabase, collectTagSetFromEntries, openExistingDatabase } from "../indexer/db/db.js";
 import { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL } from "../output/cli-hints.js";
-import { getHyphenatedArg, getOutputMode, parseDetailLevel } from "../output/context.js";
+import { getOutputMode, parseDetailLevel } from "../output/context.js";
 import { formatEventLine } from "../output/text.js";
 import { getDirname } from "../runtime.js";
 import { akmEventsList, akmEventsTail } from "./events.js";
@@ -90,9 +90,9 @@ const eventsTailCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const intervalMs = parsePositiveIntFlag(getHyphenatedArg(args, "interval-ms"), "--interval-ms");
-            const maxDurationMs = parsePositiveIntFlag(getHyphenatedArg(args, "max-duration-ms"), "--max-duration-ms");
-            const maxEvents = parsePositiveIntFlag(getHyphenatedArg(args, "max-events"), "--max-events");
+            const intervalMs = parsePositiveIntFlag(args["interval-ms"], "--interval-ms");
+            const maxDurationMs = parsePositiveIntFlag(args["max-duration-ms"], "--max-duration-ms");
+            const maxEvents = parsePositiveIntFlag(args["max-events"], "--max-events");
             const mode = getOutputMode();
             // In streaming text mode we want each event to print as soon as it
             // arrives. The polling loop emits via `onEvent`; the final result is

package/dist/commands/proposal/drain-policies.js

@@ -17,9 +17,9 @@
 import fs from "node:fs";
 import { z } from "zod";
 import { UsageError } from "../../core/errors.js";
-import { PROPOSAL_SOURCES } from "./validators/proposals.js";
+import { PROPOSAL_SOURCES } from "./repository.js";
 // Valid `generator` values for a drain rule are exactly the canonical proposal
-// `source` values (see {@link PROPOSAL_SOURCES} in src/commands/proposal/validators/proposals.ts). The
+// `source` values (see {@link PROPOSAL_SOURCES} in src/commands/proposal/repository.ts). The
 // engine matches rules via `policy.accept.find(r => r.generator === proposal.source)`,
 // so a generator that is not a real source can never match — it would be a
 // silent permanent no-op. Validate against the closed set to surface typos.

package/dist/commands/proposal/drain.js

@@ -44,7 +44,7 @@ import { info, warn } from "../../core/warn.js";
 import { executeRunner } from "../../integrations/agent/runner-dispatch.js";
 import { chatCompletion, stripJsonFences } from "../../llm/client.js";
 import { akmProposalAccept, akmProposalReject } from "./proposal.js";
-import { listProposals, recordGateDecision } from "./validators/proposals.js";
+import { listProposals, recordGateDecision } from "./repository.js";
 // ---------------------------------------------------------------------------
 // Content helpers
 // ---------------------------------------------------------------------------

package/dist/commands/proposal/legacy-import.js

@@ -0,0 +1,115 @@
+// 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/.
+/**
+ * Legacy filesystem proposal import (#578).
+ *
+ * Before 0.9.0 proposals lived as per-uuid JSON directories under
+ * `<stashDir>/.akm/proposals/` (live) and `…/proposals/archive/` (archived).
+ * The first proposal operation against a stash imports any legacy
+ * `proposal.json` files into the `proposals` table (INSERT OR IGNORE keyed on
+ * the UUID, so re-runs never duplicate) and records the stash in
+ * `proposal_fs_imports` so later invocations skip the directory walk. The
+ * legacy files are left in place untouched — they are inert after import and
+ * may be removed by the operator at leisure.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { warn } from "../../core/warn.js";
+import { hasImportedFsProposals, insertProposalIfAbsent, recordFsProposalsImport, } from "../../storage/repositories/proposals-repository.js";
+/** Legacy (pre-0.9.0) proposal directory: `<stashDir>/.akm/proposals[/archive]`. */
+function legacyProposalsRoot(stashDir, archive) {
+    const root = path.join(stashDir, ".akm", "proposals");
+    return archive ? path.join(root, "archive") : root;
+}
+/**
+ * One-shot import of legacy `proposal.json` files into the `proposals` table.
+ *
+ * Idempotent at two levels: the `proposal_fs_imports` ledger skips the
+ * directory walk after the first successful import, and INSERT OR IGNORE
+ * (keyed on the proposal UUID) protects against duplicates even if the walk
+ * re-runs. Legacy `backup.<ext>` files are inlined into `backupContent` so
+ * `akm proposal revert` keeps working for proposals accepted before 0.9.0.
+ *
+ * The legacy files are never modified or deleted — after import they are
+ * inert artifacts the operator can remove at leisure.
+ */
+export function importLegacyProposalFiles(db, stashDir) {
+    if (hasImportedFsProposals(db, stashDir))
+        return;
+    const liveRoot = legacyProposalsRoot(stashDir, false);
+    if (!fs.existsSync(liveRoot))
+        return;
+    let imported = 0;
+    for (const archive of [false, true]) {
+        const root = legacyProposalsRoot(stashDir, archive);
+        let entries;
+        try {
+            entries = fs.readdirSync(root, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name === "archive")
+                continue;
+            const proposalDir = path.join(root, entry.name);
+            const proposal = readLegacyProposalFile(proposalDir);
+            if (!proposal)
+                continue;
+            if (insertProposalIfAbsent(db, proposal, stashDir))
+                imported += 1;
+        }
+    }
+    recordFsProposalsImport(db, stashDir, imported);
+    if (imported > 0) {
+        warn(`[proposals] imported ${imported} legacy proposal file(s) from ${liveRoot} into state.db`);
+    }
+}
+/**
+ * Parse one legacy proposal directory into a {@link Proposal}, inlining the
+ * backup file (when present) as `backupContent`. Returns undefined — with a
+ * warning — when the `proposal.json` is missing, unreadable, or malformed, so
+ * a single corrupt legacy entry never blocks the import of the rest.
+ */
+function readLegacyProposalFile(proposalDir) {
+    const filePath = path.join(proposalDir, "proposal.json");
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch (err) {
+        warn(`[proposals] skipping legacy proposal at ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        typeof parsed.id !== "string" ||
+        typeof parsed.ref !== "string") {
+        warn(`[proposals] skipping legacy proposal at ${filePath}: not a proposal object`);
+        return undefined;
+    }
+    const { backup, ...rest } = parsed;
+    let backupContent;
+    if (typeof backup === "string" && backup.length > 0) {
+        try {
+            backupContent = fs.readFileSync(path.join(proposalDir, backup), "utf8");
+        }
+        catch {
+            // Backup file lost — import the proposal anyway; revert for it will
+            // surface "no backup available", same as a new-asset proposal.
+        }
+    }
+    return {
+        ...rest,
+        payload: {
+            content: rest.payload?.content ?? "",
+            ...(rest.payload?.frontmatter ? { frontmatter: rest.payload.frontmatter } : {}),
+        },
+        createdAt: rest.createdAt ?? "",
+        updatedAt: rest.updatedAt ?? rest.createdAt ?? "",
+        status: rest.status ?? "pending",
+        source: rest.source ?? "import",
+        ...(backupContent !== undefined ? { backupContent } : {}),
+    };
+}

package/dist/commands/proposal/proposal-cli.js

@@ -97,7 +97,7 @@ const proposalAcceptCommand = defineJsonCommand({
                 process.stderr.write("Aborted.\n");
                 return;
             }
-            const { listProposals } = await import("./validators/proposals.js");
+            const { listProposals } = await import("./repository.js");
             const stashDir = resolveStashDir();
             const rawMaxDiff = args["max-diff-lines"] ? Number.parseInt(String(args["max-diff-lines"]), 10) : undefined;
             if (rawMaxDiff !== undefined && (Number.isNaN(rawMaxDiff) || rawMaxDiff < 0)) {
@@ -191,7 +191,7 @@ const proposalRejectCommand = defineJsonCommand({
                 process.stderr.write("Aborted.\n");
                 return;
             }
-            const { listProposals } = await import("./validators/proposals.js");
+            const { listProposals } = await import("./repository.js");
             const stashDir = resolveStashDir();
             const rawMaxDiff = args["max-diff-lines"] ? Number.parseInt(String(args["max-diff-lines"]), 10) : undefined;
             if (rawMaxDiff !== undefined && (Number.isNaN(rawMaxDiff) || rawMaxDiff < 0)) {
@@ -390,7 +390,7 @@ const proposalDrainCommand = defineJsonCommand({
         // second read (engine API owned by another agent — not changed here).
         let excludeIds;
         if (olderThanMs !== undefined) {
-            const { listProposals } = await import("./validators/proposals.js");
+            const { listProposals } = await import("./repository.js");
             const now = Date.now();
             excludeIds = new Set(listProposals(stashDir, { status: "pending" })
                 // Fail SAFE: exclude a proposal when its age cannot be computed

package/dist/commands/proposal/proposal.js

@@ -15,7 +15,8 @@ import { resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { archiveProposal, createProposal, diffProposal, getProposal, isProposalSkipped, listProposals, promoteProposal, resolveProposalId, revertProposal, validateProposal, } from "./validators/proposals.js";
+import { archiveProposal, createProposal, diffProposal, getProposal, isProposalSkipped, listProposals, promoteProposal, resolveProposalId, revertProposal, } from "./repository.js";
+import { validateProposal } from "./validators/proposals.js";
 // ── Shared helpers ──────────────────────────────────────────────────────────
 function resolveStash(stashDir) {
     if (stashDir)

package/dist/commands/proposal/propose.js

@@ -24,7 +24,7 @@ import { resolveProcessAgentProfile } from "../../integrations/agent/config.js";
 import { buildProposePrompt, parseAgentProposalPayload } from "../../integrations/agent/prompts.js";
 import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
 import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigFromDisk, resolveAgentProfile, } from "../agent/agent-support.js";
-import { createProposal, isProposalSkipped, } from "./validators/proposals.js";
+import { createProposal, isProposalSkipped, } from "./repository.js";
 function failureEnvelope(result, type, name, fallbackReason = "non_zero_exit") {
     return {
         ...baseFailureFields(result, fallbackReason),