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

package/dist/commands/lint/fact-linter.js

@@ -0,0 +1,39 @@
+// 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 { BaseLinter } from "./base-linter.js";
+/** Recommended `category` values for facts (see docs/design/fact-asset-type.md). */
+const KNOWN_CATEGORIES = new Set(["personal", "team", "project", "convention", "meta"]);
+/**
+ * Linter for `facts/` assets.
+ *
+ * Extra check beyond base:
+ *   - `missing-category`: a fact without a non-empty `category` frontmatter
+ *     key. Category scopes the fact (personal/team/project/convention/meta)
+ *     and drives how it is surfaced/injected, so it is expected. Reported as a
+ *     non-fixable warning — we cannot infer the right scope automatically.
+ */
+export class FactLinter extends BaseLinter {
+    types = ["facts"];
+    lint(ctx) {
+        const issues = this.runBaseChecks(ctx);
+        const category = typeof ctx.data.category === "string" ? ctx.data.category.trim() : "";
+        if (!category) {
+            issues.push({
+                file: ctx.relPath,
+                issue: "missing-category",
+                detail: "fact is missing a `category` (personal|team|project|convention|meta)",
+                fixed: false,
+            });
+        }
+        else if (!KNOWN_CATEGORIES.has(category)) {
+            issues.push({
+                file: ctx.relPath,
+                issue: "missing-category",
+                detail: `unrecognized category "${category}" (expected one of: ${[...KNOWN_CATEGORIES].join(", ")})`,
+                fixed: false,
+            });
+        }
+        return issues;
+    }
+}

package/dist/commands/lint/index.js

@@ -20,6 +20,7 @@ const STASH_SUBDIRS = [
     "lessons",
     "tasks",
     "knowledge",
+    "facts",
 ];
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function collectYamlFiles(dir) {
@@ -85,7 +86,8 @@ export function akmLint(options = {}) {
     const fix = options.fix ?? false;
     const fixed = [];
     const flagged = [];
-    for (const subdir of STASH_SUBDIRS) {
+    const dirsToScan = options.typeFilter ? STASH_SUBDIRS.filter((d) => d === options.typeFilter) : STASH_SUBDIRS;
+    for (const subdir of dirsToScan) {
         const dirPath = path.join(stashRoot, subdir);
         // Tasks are .yml files; everything else is .md
         const files = subdir === "tasks" ? collectYamlFiles(dirPath) : collectMarkdownFiles(dirPath);
@@ -97,7 +99,9 @@ export function akmLint(options = {}) {
                 if (entry.isDirectory()) {
                     const subdirIssues = linter.lintDirectory(path.join(dirPath, entry.name), stashRoot);
                     for (const issue of subdirIssues) {
-                        if (issue.fixed) {
+                        // Tristate-safe: only `true` counts as fixed; `false` and "failed"
+                        // are both flagged.
+                        if (issue.fixed === true) {
                             fixed.push(issue);
                         }
                         else {
@@ -108,6 +112,9 @@ export function akmLint(options = {}) {
             }
         }
         for (const filePath of files) {
+            // Skip registry-cached read-only files — --fix must not mutate them.
+            if (filePath.includes("/.cache/") || filePath.includes("/registry/"))
+                continue;
             const relPath = path.relative(stashRoot, filePath);
             let raw;
             try {
@@ -142,10 +149,11 @@ export function akmLint(options = {}) {
                     fileDeleted = true;
                     fixed.push(issue);
                 }
-                else if (issue.fixed) {
+                else if (issue.fixed === true) {
                     fixed.push(issue);
                 }
                 else {
+                    // fixed === false (not fixable / no fix requested) or "failed" (fix attempted but threw)
                     flagged.push(issue);
                 }
             }
@@ -159,16 +167,26 @@ export function akmLint(options = {}) {
     // findings go into `flagged`, never `fixed`.
     const envRoots = [stashRoot, ...extraStashRoots];
     for (const root of envRoots) {
-        const dir = path.join(root, "env");
-        if (!fs.existsSync(dir))
-            continue;
-        for (const envPath of collectEnvFiles(dir)) {
-            const baseName = path.basename(envPath, ".env");
-            // "default" (or empty) maps to ".env" → env:default
-            const ref = baseName === "" ? "env:default" : `env:${baseName}`;
-            const relPath = path.relative(root, envPath);
-            for (const issue of checkEnvForDangerousKeys(envPath, relPath, ref)) {
-                flagged.push(issue);
+        // The `env` assets live under `env/` (ref prefix `env:`); whole-file
+        // `secret` assets live under `secrets/` (canonical ref prefix `secret:`,
+        // singular). Map the scan directory to its canonical ref prefix so the
+        // finding's `Ref:` field matches what `akm show`/`akm secret` accept.
+        for (const { scanSubdir, refPrefix } of [
+            { scanSubdir: "env", refPrefix: "env" },
+            { scanSubdir: "secrets", refPrefix: "secret" },
+        ]) {
+            const dir = path.join(root, scanSubdir);
+            if (!fs.existsSync(dir))
+                continue;
+            for (const envPath of collectEnvFiles(dir)) {
+                const baseName = path.basename(envPath, ".env");
+                // A dotfile literally named `.env` has an empty baseName — use the full
+                // basename so it doesn't collide with `default.env` → refPrefix:default.
+                const ref = baseName === "" ? `${refPrefix}:.env` : `${refPrefix}:${baseName}`;
+                const relPath = path.relative(root, envPath);
+                for (const issue of checkEnvForDangerousKeys(envPath, relPath, ref)) {
+                    flagged.push(issue);
+                }
             }
         }
     }

package/dist/commands/lint/memory-linter.js

@@ -33,7 +33,7 @@ export class MemoryLinter extends BaseLinter {
                         file: ctx.relPath,
                         issue: "orphaned-stub",
                         detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
-                        fixed: false,
+                        fixed: "failed",
                     });
                 }
                 // Signal caller to skip remaining checks via a sentinel issue

package/dist/commands/lint/registry.js

@@ -4,6 +4,7 @@
 import { AgentLinter } from "./agent-linter.js";
 import { CommandLinter } from "./command-linter.js";
 import { DefaultLinter } from "./default-linter.js";
+import { FactLinter } from "./fact-linter.js";
 import { KnowledgeLinter } from "./knowledge-linter.js";
 import { MemoryLinter } from "./memory-linter.js";
 import { SkillLinter } from "./skill-linter.js";
@@ -18,15 +19,19 @@ const LINTERS = [
     new KnowledgeLinter(),
     new SkillLinter(),
     new TaskLinter(),
-    new DefaultLinter(),
+    new FactLinter(),
 ];
+// Single shared DefaultLinter instance — used both as the explicit "lessons"
+// handler and as the fallback for any unrecognised asset type.
+const DEFAULT_LINTER = new DefaultLinter();
 const LINTER_MAP = new Map();
 for (const linter of LINTERS) {
     for (const t of linter.types) {
         LINTER_MAP.set(t, linter);
     }
 }
-const DEFAULT_LINTER = new DefaultLinter();
+// Register "lessons" explicitly so there is only one DefaultLinter instance.
+LINTER_MAP.set("lessons", DEFAULT_LINTER);
 /**
  * Return the appropriate linter for the given stash subdirectory name.
  * Falls back to `DefaultLinter` for unknown types.

package/dist/commands/lint/task-linter.js

@@ -28,9 +28,9 @@ export class TaskLinter extends BaseLinter {
         if (!("schedule" in ctx.data) || typeof ctx.data.schedule !== "string" || ctx.data.schedule.trim() === "") {
             missing.push("schedule");
         }
-        // enabled: must be present (boolean — value of false is valid)
-        if (!("enabled" in ctx.data)) {
-            missing.push("enabled");
+        // enabled: must be present AND a boolean (value of false is valid, but "yes" / 1 are not)
+        if (!("enabled" in ctx.data) || typeof ctx.data.enabled !== "boolean") {
+            missing.push("enabled (must be a boolean)");
         }
         // At least one of: prompt, workflow, or command
         const hasTarget = "prompt" in ctx.data || "workflow" in ctx.data || "command" in ctx.data;

package/dist/commands/lint/workflow-linter.js

@@ -2,6 +2,7 @@
 // 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 fs from "node:fs";
+import { parseWorkflow } from "../../workflows/parser.js";
 import { BaseLinter } from "./base-linter.js";
 const PLACEHOLDER_STRINGS = ["Describe what this workflow accomplishes", "Example Workflow"];
 /**
@@ -32,7 +33,7 @@ export class WorkflowLinter extends BaseLinter {
                         file: ctx.relPath,
                         issue: "placeholder-stub",
                         detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
-                        fixed: false,
+                        fixed: "failed",
                     });
                 }
                 return issues;
@@ -44,6 +45,30 @@ export class WorkflowLinter extends BaseLinter {
                 fixed: false,
             });
         }
+        const isReadOnly = ctx.filePath.includes("/.cache/") || ctx.filePath.includes("/registry/");
+        if (!isReadOnly) {
+            try {
+                const result = parseWorkflow(ctx.raw, { path: ctx.filePath });
+                if (!result.ok) {
+                    for (const err of result.errors ?? []) {
+                        issues.push({
+                            file: ctx.relPath,
+                            issue: "invalid-workflow-structure",
+                            detail: err.message ?? String(err),
+                            fixed: false,
+                        });
+                    }
+                }
+            }
+            catch (e) {
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "invalid-workflow-structure",
+                    detail: `workflow parser error: ${e instanceof Error ? e.message : String(e)}`,
+                    fixed: false,
+                });
+            }
+        }
         return issues;
     }
     #checkPlaceholderStub(body) {

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.
@@ -39,12 +39,20 @@ const GeneratorSchema = z.enum(PROPOSAL_SOURCES, {
 export const PERSONAL_STASH = {
     name: "personal-stash",
     accept: [
-        // Extract proposals carry freshly-pulled real content — accept when present.
-        { generator: "extract", minContentLines: 1 },
+        // Extract proposals carry freshly-pulled real content — accept when present,
+        // but cap the diff for parity with reflect(80)/consolidate(200): an
+        // arbitrarily large extract should not auto-promote with zero LLM calls.
+        { generator: "extract", minContentLines: 1, maxDiffLines: 200 },
         // Reflect refinements: accept small ones; larger refinements defer to review.
         { generator: "reflect", maxDiffLines: 80 },
         // Consolidate within the diff band; mid-band lands in `defer` below.
         { generator: "consolidate", maxDiffLines: 200 },
+        // Recombine: accept only confirmed type:lesson proposals (promoted by the
+        // recombine confidence gate) within the diff band. type:hypothesis proposals
+        // have no matching rule here and stay pending on the audited-autonomous
+        // queue until recombine supersedes them or the 90-day TTL sweeps them —
+        // there is no manual-review rung (06-M3).
+        { generator: "recombine", requireType: "lesson", maxDiffLines: 200 },
     ],
     rejectEmpty: true,
     // Mid-band consolidate, distill duplicates, and contradiction escalations are
@@ -83,6 +91,7 @@ const DrainAcceptRuleSchema = z
     generator: GeneratorSchema,
     maxDiffLines: z.number().int().positive().optional(),
     minContentLines: z.number().int().nonnegative().optional(),
+    requireType: z.string().optional(),
 })
     .strict();
 const DrainPolicySchema = z

package/dist/commands/proposal/drain.js

@@ -9,7 +9,7 @@
  * the engine behind `akm proposal drain` and (later) the `triage` improve
  * pre-pass.
  *
- * Design (see docs/technical/proposal-triage-implementation-plan.md):
+ * Design (see docs/archive/proposal-triage-implementation-plan.md):
  *   - Reuses `listProposals` (no source filter — generator filtering is
  *     in-memory) and the `akmProposalAccept` / `akmProposalReject` wrappers from
  *     `proposal.ts` so the standard `promoted` / `rejected` events are emitted.
@@ -36,17 +36,15 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { assertNever } from "../../core/assert.js";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset/asset-spec.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { appendEvent } from "../../core/events.js";
 import { info, warn } from "../../core/warn.js";
-import { runAgent } from "../../integrations/agent/index.js";
-import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.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
 // ---------------------------------------------------------------------------
@@ -80,7 +78,16 @@ export function classifyProposal(proposal, policy, maxDiffLines) {
     if (policy.rejectEmpty && isEmptyDiff(proposal)) {
         return { verdict: "reject", reason: "empty diff", gate: { reason: "empty-diff" } };
     }
-    const rule = policy.accept.find((r) => r.generator === proposal.source);
+    const rule = policy.accept.find((r) => {
+        if (r.generator !== proposal.source)
+            return false;
+        if (r.requireType !== undefined) {
+            const fm = parseFrontmatter(proposal.payload.content ?? "").data;
+            if (typeof fm.type !== "string" || fm.type !== r.requireType)
+                return false;
+        }
+        return true;
+    });
     if (rule) {
         const lines = contentLineCount(content);
         const body = contentBodyLineCount(content);
@@ -200,59 +207,38 @@ export function parseJudgmentVerdict(raw) {
     return { decision, reason: typeof reason === "string" ? reason : "" };
 }
 /**
- * Dispatch a single judgment prompt to the resolved runner. The switch mirrors
- * the canonical consumer at `reflect.ts:1060-1090`: llm → `chatCompletion`
- * (no filesystem), agent → `runAgent`, sdk → `runOpencodeSdk`.
+ * Dispatch a single judgment prompt to the resolved runner via the unified
+ * {@link executeRunner} seam (X3). The `llm` arm is drain-specific (wraps
+ * `chatCompletion` — no filesystem) so it is supplied as the `llm` handler; the
+ * byte-identical `agent` / `sdk` arms route to the default profile runners (or
+ * the injected {@link JudgmentSeams} test fakes). A failed spawn warns and
+ * yields `null`, matching the prior per-arm behavior.
  */
 async function dispatchJudgment(runner, prompt, seams) {
-    let raw;
-    switch (runner.kind) {
-        case "llm": {
-            const messages = [{ role: "user", content: prompt }];
-            raw = seams.chat
-                ? await seams.chat(runner, messages)
-                : await chatCompletion(runner.connection, messages, {
-                    ...(runner.timeoutMs !== undefined ? { timeoutMs: runner.timeoutMs } : {}),
-                });
-            break;
-        }
-        case "agent": {
-            const stdout = await runProfileJudgment(seams.runAgentFn ?? runAgent, runner.profile, prompt, "agent", runner.timeoutMs);
-            if (stdout === null)
-                return null;
-            raw = stdout;
-            break;
-        }
-        case "sdk": {
-            const stdout = await runProfileJudgment(seams.runSdkFn ?? runOpencodeSdk, runner.profile, prompt, "sdk", runner.timeoutMs);
-            if (stdout === null)
-                return null;
-            raw = stdout;
-            break;
-        }
-        default:
-            // Exhaustiveness arm (H1): a 4th RunnerSpec kind becomes a compile error
-            // here instead of leaving `raw` undefined at runtime.
-            return assertNever(runner);
-    }
-    return parseJudgmentVerdict(raw);
-}
-/**
- * Shared spawn-runner dispatch for the byte-identical `agent` / `sdk` arms: run
- * the profile-based runner, log a labelled warning on failure, and return the
- * captured stdout (or `null` on failure). `label` only changes the warn prefix.
- */
-async function runProfileJudgment(run, profile, prompt, label, timeoutMs) {
-    const result = await run(profile, prompt, {
+    const runOptions = {
         stdio: "captured",
         parseOutput: "text",
-        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        ...(runner.timeoutMs !== undefined ? { timeoutMs: runner.timeoutMs } : {}),
+    };
+    const result = await executeRunner(runner, prompt, runOptions, {
+        llm: async (spec, p) => {
+            const messages = [{ role: "user", content: p }];
+            const raw = seams.chat
+                ? await seams.chat(spec, messages)
+                : await chatCompletion(spec.connection, messages, {
+                    ...(spec.timeoutMs !== undefined ? { timeoutMs: spec.timeoutMs } : {}),
+                });
+            // chatCompletion has no failure envelope — a returned string is success.
+            return { ok: true, exitCode: 0, stdout: raw, stderr: "", durationMs: 0 };
+        },
+        ...(seams.runAgentFn ? { runAgent: seams.runAgentFn } : {}),
+        ...(seams.runSdkFn ? { runSdk: seams.runSdkFn } : {}),
     });
     if (!result.ok) {
-        warn(`[triage] judgment ${label} failed: ${result.error ?? result.reason ?? "unknown error"}`);
+        warn(`[triage] judgment ${runner.kind} failed: ${result.error ?? result.reason ?? "unknown error"}`);
         return null;
     }
-    return result.stdout;
+    return parseJudgmentVerdict(result.stdout);
 }
 /**
  * Run the judgment tier over the deferred items. The runner only *judges*; the
@@ -361,6 +347,14 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
     // — these are re-stamped `no-judge-configured` when no runner resolves them.
     const needsJudge = new Set();
     for (const proposal of pending) {
+        // Do NOT reclassify a proposal that was already conclusively stamped
+        // `auto-rejected` by a prior gate run (e.g. the improve confidence gate).
+        // Overwriting an authoritative rejection with `auto-accepted` would corrupt
+        // the audit trail and silently promote content the gate explicitly rejected.
+        // Such proposals remain pending until the TTL expires them — the queue is
+        // audited-autonomous; no manual-review rung exists (06-M3).
+        if (proposal.gateDecision?.outcome === "auto-rejected")
+            continue;
         const decision = classifyProposal(proposal, opts.policy, opts.maxDiffLines);
         if (decision === null)
             continue;

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 } : {}),
+    };
+}