akm-cli 0.8.6 → 0.8.14

package/dist/{core → commands/proposal/validators}/proposals.js

@@ -2,50 +2,58 @@
 // 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/.
 /**
- * Proposal substrate (#225).
+ * Proposal substrate (#225, storage consolidated in #578).
  *
  * One durable proposal store for every future reflection / generation flow
  * (`akm reflect`, `akm propose`, `akm distill`, lesson distillation, …).
- * Proposals are *queue state*, not source-of-truth assets — they sit on disk
- * waiting for human (or automated) review and only become assets after
+ * Proposals are *queue state*, not source-of-truth assets — they sit in the
+ * queue waiting for human (or automated) review and only become assets after
  * `akm proposal accept` validates and promotes them via
  * {@link writeAssetToSource}.
  *
- * # Storage layout
+ * # Storage
  *
- *   <stashRoot>/.akm/proposals/<id>/proposal.json
- *   <stashRoot>/.akm/proposals/archive/<id>/proposal.json
+ * The canonical store is the `proposals` table in `state.db` (SQLite, WAL
+ * mode — see `src/core/state-db.ts`). Rows are partitioned by `stash_dir` so
+ * multi-stash installs keep independent queues, and the `status` column
+ * distinguishes the live queue (`pending`) from the archive (`accepted` /
+ * `rejected` / `reverted`). There is no separate archive location — archival
+ * is a status flip, and the full audit trail (review outcome, reason, backup
+ * content for revert) lives on the row.
  *
- * One directory per proposal id (a stable `crypto.randomUUID()`), so multiple
- * proposals can target the same `ref` without filesystem collisions.
+ * ## Legacy filesystem import
  *
- * # Why direct fs (and not `writeAssetToSource`)
+ * 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 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.
  *
- * The architectural rule "all writes go through `writeAssetToSource`" applies
- * to *assets*. Proposals are **not** assets — they live outside the asset tree
- * (under `.akm/proposals/`, parallel to how `events.jsonl` lives outside the
- * asset tree). Routing them through `writeAssetToSource` would force them into
- * a `TYPE_DIRS` slot, would commit them to git, and would leak unaccepted
- * drafts through the normal indexer. None of that is what we want for queue
- * state. The {@link promoteProposal} step is the bridge: it routes the
- * accepted payload through `writeAssetToSource` so the actual asset write
- * still funnels through the single dispatch point in
- * `src/core/write-source.ts`.
+ * # Why the queue bypasses `writeAssetToSource`
  *
- * Direct `fs` IO here is deliberate and the only place in the v1 codebase
- * that bypasses `writeAssetToSource` for "stash-adjacent" durable state. See
- * CLAUDE.md ("Writes" section) for the contract.
+ * The architectural rule "all writes go through `writeAssetToSource`" applies
+ * to *assets*. Proposals are **not** assets — they live outside the asset
+ * tree (in state.db, parallel to how events do). Routing them through
+ * `writeAssetToSource` would force them into a `TYPE_DIRS` slot, would commit
+ * them to git, and would leak unaccepted drafts through the normal indexer.
+ * The {@link promoteProposal} step is the bridge: it routes the accepted
+ * payload through `writeAssetToSource` so the actual asset write still
+ * funnels through the single dispatch point in `src/core/write-source.ts`.
  */
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { makeAssetRef, parseAssetRef } from "./asset-ref";
-import { resolveAssetPathFromName, TYPE_DIRS } from "./asset-spec";
-import { NotFoundError, UsageError } from "./errors";
-import { appendEvent } from "./events";
-import { runProposalValidators } from "./proposal-validators";
-import { warn } from "./warn";
-import { resolveWriteTarget, writeAssetToSource } from "./write-source";
+import { makeAssetRef, parseAssetRef } from "../../../core/asset/asset-ref.js";
+import { resolveAssetPathFromName, TYPE_DIRS } from "../../../core/asset/asset-spec.js";
+import { NotFoundError, UsageError } from "../../../core/errors.js";
+import { appendEvent } from "../../../core/events.js";
+import { getStateDbPath, getStateProposal, hasImportedFsProposals, insertProposalIfAbsent, listStateProposalIdsByPrefix, listStateProposals, openStateDatabase, recordFsProposalsImport, upsertProposal, } from "../../../core/state-db.js";
+import { warn } from "../../../core/warn.js";
+import { commitWriteTargetBoundary, formatRefForMessage, resolveWriteTarget, writeAssetToSource, } from "../../../core/write-source.js";
+import { runProposalValidators } from "./proposal-validators.js";
 // ── Source allow-list (F-4 / #385) ──────────────────────────────────────────
 /**
  * Curated allow-list of valid `source` values for proposals (F-4 / #385).
@@ -131,21 +139,7 @@ function cooldownMsForSource(source) {
 function contentHash(content) {
     return createHash("sha256").update(content, "utf8").digest("hex");
 }
-// ── Path helpers ────────────────────────────────────────────────────────────
-/**
- * Resolve `<stashRoot>/.akm/proposals` (or its archive subdirectory). Direct
- * fs paths because proposal storage is queue state, not asset state — see the
- * module docblock for the architectural carve-out.
- */
-export function getProposalsRoot(stashDir, archive = false) {
-    return archive ? path.join(stashDir, ".akm", "proposals", "archive") : path.join(stashDir, ".akm", "proposals");
-}
-function proposalDir(stashDir, id, archive) {
-    return path.join(getProposalsRoot(stashDir, archive), id);
-}
-function proposalFile(stashDir, id, archive) {
-    return path.join(proposalDir(stashDir, id, archive), "proposal.json");
-}
+// ── Store access ─────────────────────────────────────────────────────────────
 function nowIso(ctx) {
     const fn = ctx?.now ?? Date.now;
     return new Date(fn()).toISOString();
@@ -154,35 +148,124 @@ function newId(ctx) {
     const fn = ctx?.randomUUID ?? randomUUID;
     return fn();
 }
-// ── Read / write primitives ─────────────────────────────────────────────────
-function readProposalFile(filePath) {
-    let raw;
+/**
+ * Open the state database (honouring the `ctx.dbPath` test seam), run the
+ * legacy filesystem import for `stashDir` if it has not happened yet, hand the
+ * connection to `fn`, and close it in a `finally`. Every public function in
+ * this module funnels its store access through here so the legacy import is
+ * guaranteed to have run before any read or write.
+ */
+function withProposalsDb(stashDir, ctx, fn) {
+    const db = openStateDatabase(ctx?.dbPath ?? getStateDbPath());
     try {
-        raw = fs.readFileSync(filePath, "utf8");
+        importLegacyProposalFiles(db, stashDir);
+        return fn(db);
     }
-    catch (err) {
-        throw new NotFoundError(`Proposal not found at ${filePath}.`, "FILE_NOT_FOUND", `The proposal file is missing or unreadable: ${err.message}`);
+    finally {
+        db.close();
     }
+}
+// ── Legacy filesystem import (#578) ─────────────────────────────────────────
+/** 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.
+ */
+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(raw);
+        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
     }
     catch (err) {
-        throw new UsageError(`Proposal file at ${filePath} is not valid JSON: ${err.message}`, "INVALID_JSON_ARGUMENT", "Re-create the proposal or remove the corrupt file under .akm/proposals/<id>/.");
+        warn(`[proposals] skipping legacy proposal at ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
     }
-    if (typeof parsed !== "object" || parsed === null) {
-        throw new UsageError(`Proposal file at ${filePath} is not a JSON object.`, "INVALID_JSON_ARGUMENT");
+    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;
     }
-    return parsed;
-}
-function writeProposalFile(filePath, proposal) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, `${JSON.stringify(proposal, null, 2)}\n`, "utf8");
+    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 } : {}),
+    };
 }
 // ── Public API ──────────────────────────────────────────────────────────────
 /**
  * Create a new pending proposal. The id is a stable random UUID, so two
- * proposals with the same `ref` never collide on disk.
+ * proposals with the same `ref` never collide.
  *
  * **Dedup / cooldown guard** (F-2 / #363):
  *
@@ -196,7 +279,7 @@ function writeProposalFile(filePath, proposal) {
  *      others: 7 d). Bypass with `force: true`.
  *
  * When a guard fires the function returns a `CreateProposalSkipped` record
- * instead of writing to disk. Use {@link isProposalSkipped} to detect it.
+ * instead of writing. Use {@link isProposalSkipped} to detect it.
  */
 export function createProposal(stashDir, input, ctx) {
     // F-4 / #385: Validate source against the allow-list. Unknown values are
@@ -250,173 +333,144 @@ export function createProposal(stashDir, input, ctx) {
         }
     }
     const normalizedRef = makeAssetRef(parsedRef.type, parsedRef.name, parsedRef.origin);
-    if (!input.force) {
-        const newHash = contentHash(input.payload.content);
-        const nowMs = (ctx?.now ?? Date.now)();
-        const cooldownMs = cooldownMsForSource(input.source);
-        // Scan pending proposals for ref+source matches.
-        const pending = listProposals(stashDir, { ref: normalizedRef, status: "pending" }).filter((p) => p.source === input.source);
-        if (pending.length > 0) {
-            // Check for identical content hash first (silent skip).
-            const hashMatch = pending.find((p) => contentHash(p.payload.content) === newHash);
-            if (hashMatch) {
-                return {
-                    skipped: true,
-                    reason: "content_hash_match",
-                    message: `Identical proposal for ${normalizedRef} already pending (id: ${hashMatch.id}).`,
-                    existingProposalId: hashMatch.id,
-                };
-            }
-            // Duplicate pending for same ref+source (different content).
-            const firstPending = pending[0];
+    return withProposalsDb(stashDir, ctx, (db) => {
+        if (!input.force) {
+            const skip = checkDedupAndCooldown(db, stashDir, normalizedRef, input, ctx);
+            if (skip)
+                return skip;
+        }
+        const created = nowIso(ctx);
+        // Phase 6A: validate confidence is a finite number in [0, 1]. Anything else
+        // is dropped silently — we never store NaN, Infinity, or out-of-range values.
+        // Callers that mis-report confidence should not poison the auto-accept gate.
+        const sanitizedConfidence = typeof input.confidence === "number" &&
+            Number.isFinite(input.confidence) &&
+            input.confidence >= 0 &&
+            input.confidence <= 1
+            ? input.confidence
+            : undefined;
+        const proposal = {
+            id: newId(ctx),
+            ref: normalizedRef,
+            status: "pending",
+            source: input.source,
+            ...(input.sourceRun !== undefined ? { sourceRun: input.sourceRun } : {}),
+            createdAt: created,
+            updatedAt: created,
+            payload: {
+                content: input.payload.content,
+                ...(input.payload.frontmatter !== undefined ? { frontmatter: input.payload.frontmatter } : {}),
+            },
+            ...(sanitizedConfidence !== undefined ? { confidence: sanitizedConfidence } : {}),
+        };
+        upsertProposal(db, proposal, stashDir);
+        return proposal;
+    });
+}
+/**
+ * Evaluate the F-2 dedup / cooldown guards against the store. Returns the
+ * skip record when a guard fires, or undefined when the create may proceed.
+ */
+function checkDedupAndCooldown(db, stashDir, normalizedRef, input, ctx) {
+    const newHash = contentHash(input.payload.content);
+    const nowMs = (ctx?.now ?? Date.now)();
+    const cooldownMs = cooldownMsForSource(input.source);
+    // Scan pending proposals for ref+source matches.
+    const pending = listStateProposals(db, { stashDir, ref: normalizedRef, status: "pending" }).filter((p) => p.source === input.source);
+    if (pending.length > 0) {
+        // Check for identical content hash first (silent skip).
+        const hashMatch = pending.find((p) => contentHash(p.payload.content) === newHash);
+        if (hashMatch) {
             return {
                 skipped: true,
-                reason: "duplicate_pending",
-                message: `A pending proposal for ${normalizedRef} from source "${input.source}" already exists (id: ${firstPending?.id ?? "unknown"}). Pass force:true to enqueue alongside it.`,
-                existingProposalId: firstPending?.id,
+                reason: "content_hash_match",
+                message: `Identical proposal for ${normalizedRef} already pending (id: ${hashMatch.id}).`,
+                existingProposalId: hashMatch.id,
             };
         }
-        // Check cooldown against recently archived rejected proposals.
-        const rejected = listProposals(stashDir, { ref: normalizedRef, status: "rejected", includeArchive: true })
-            .filter((p) => p.source === input.source)
-            .sort((a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime());
-        if (rejected.length > 0 && rejected[0] !== undefined) {
-            const mostRecent = rejected[0];
-            // Check content hash against recently rejected.
-            if (contentHash(mostRecent.payload.content) === newHash) {
-                return {
-                    skipped: true,
-                    reason: "content_hash_match",
-                    message: `Identical proposal for ${normalizedRef} was already rejected (id: ${mostRecent.id}).`,
-                    existingProposalId: mostRecent.id,
-                };
-            }
-            // Check cooldown window.
-            const rejectedAt = new Date(mostRecent.updatedAt ?? 0).getTime();
-            if (nowMs - rejectedAt < cooldownMs) {
-                const cooldownDays = cooldownMs / MS_PER_DAY;
-                const remainingDays = Math.ceil((cooldownMs - (nowMs - rejectedAt)) / MS_PER_DAY);
-                return {
-                    skipped: true,
-                    reason: "cooldown",
-                    message: `Proposal for ${normalizedRef} from source "${input.source}" is in cooldown ` +
-                        `(${cooldownDays}d window, ~${remainingDays}d remaining). Pass force:true to bypass.`,
-                    existingProposalId: mostRecent.id,
-                };
-            }
+        // Duplicate pending for same ref+source (different content).
+        const firstPending = pending[0];
+        return {
+            skipped: true,
+            reason: "duplicate_pending",
+            message: `A pending proposal for ${normalizedRef} from source "${input.source}" already exists (id: ${firstPending?.id ?? "unknown"}). Pass force:true to enqueue alongside it.`,
+            existingProposalId: firstPending?.id,
+        };
+    }
+    // Check cooldown against recently rejected proposals.
+    const rejected = listStateProposals(db, { stashDir, ref: normalizedRef, status: "rejected" })
+        .filter((p) => p.source === input.source)
+        .sort((a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime());
+    const mostRecent = rejected[0];
+    if (mostRecent !== undefined) {
+        // Check content hash against recently rejected.
+        if (contentHash(mostRecent.payload.content) === newHash) {
+            return {
+                skipped: true,
+                reason: "content_hash_match",
+                message: `Identical proposal for ${normalizedRef} was already rejected (id: ${mostRecent.id}).`,
+                existingProposalId: mostRecent.id,
+            };
+        }
+        // Check cooldown window.
+        const rejectedAt = new Date(mostRecent.updatedAt ?? 0).getTime();
+        if (nowMs - rejectedAt < cooldownMs) {
+            const cooldownDays = cooldownMs / MS_PER_DAY;
+            const remainingDays = Math.ceil((cooldownMs - (nowMs - rejectedAt)) / MS_PER_DAY);
+            return {
+                skipped: true,
+                reason: "cooldown",
+                message: `Proposal for ${normalizedRef} from source "${input.source}" is in cooldown ` +
+                    `(${cooldownDays}d window, ~${remainingDays}d remaining). Pass force:true to bypass.`,
+                existingProposalId: mostRecent.id,
+            };
         }
     }
-    const id = newId(ctx);
-    const created = nowIso(ctx);
-    // Phase 6A: validate confidence is a finite number in [0, 1]. Anything else
-    // is dropped silently — we never store NaN, Infinity, or out-of-range values.
-    // Callers that mis-report confidence should not poison the auto-accept gate.
-    const sanitizedConfidence = typeof input.confidence === "number" &&
-        Number.isFinite(input.confidence) &&
-        input.confidence >= 0 &&
-        input.confidence <= 1
-        ? input.confidence
-        : undefined;
-    const proposal = {
-        id,
-        ref: normalizedRef,
-        status: "pending",
-        source: input.source,
-        ...(input.sourceRun !== undefined ? { sourceRun: input.sourceRun } : {}),
-        createdAt: created,
-        updatedAt: created,
-        payload: {
-            content: input.payload.content,
-            ...(input.payload.frontmatter !== undefined ? { frontmatter: input.payload.frontmatter } : {}),
-        },
-        ...(sanitizedConfidence !== undefined ? { confidence: sanitizedConfidence } : {}),
-    };
-    writeProposalFile(proposalFile(stashDir, id, false), proposal);
-    return proposal;
+    return undefined;
 }
 /**
- * List every proposal under the stash. By default returns pending proposals
- * from the live queue; pass `{ includeArchive: true }` to include rejected /
- * accepted entries that have been moved aside.
+ * List proposals for one stash. By default returns only the live (pending)
+ * queue; pass `{ includeArchive: true }` to include accepted / rejected /
+ * reverted entries as well.
  */
-export function listProposals(stashDir, options = {}) {
-    const out = [];
-    const roots = [{ dir: getProposalsRoot(stashDir, false), archive: false }];
-    if (options.includeArchive) {
-        roots.push({ dir: getProposalsRoot(stashDir, true), archive: true });
-    }
-    for (const { dir } of roots) {
-        if (!fs.existsSync(dir))
-            continue;
-        let entries;
-        try {
-            entries = fs.readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            continue;
+export function listProposals(stashDir, options = {}, ctx) {
+    return withProposalsDb(stashDir, ctx, (db) => {
+        // Without includeArchive, only the live queue is visible — an explicit
+        // non-pending status filter therefore matches nothing (mirrors the
+        // historical live-directory scan).
+        if (!options.includeArchive && options.status !== undefined && options.status !== "pending") {
+            return [];
         }
-        for (const entry of entries) {
-            // Skip the archive subdirectory when iterating the live queue.
-            if (!entry.isDirectory())
-                continue;
-            if (entry.name === "archive")
-                continue;
-            const filePath = path.join(dir, entry.name, "proposal.json");
-            if (!fs.existsSync(filePath))
-                continue;
+        const status = options.includeArchive ? options.status : "pending";
+        return listStateProposals(db, {
+            stashDir,
+            ...(status !== undefined ? { status } : {}),
+            ...(options.ref !== undefined ? { ref: options.ref } : {}),
+        }).filter((p) => {
+            if (!options.type)
+                return true;
             try {
-                out.push(readProposalFile(filePath));
+                return parseAssetRef(p.ref).type === options.type;
             }
             catch {
-                // Surface invalid proposal files via a synthetic stub so callers can
-                // see something in `akm proposal list` rather than the file
-                // disappearing silently.
-                out.push({
-                    id: entry.name,
-                    ref: "unknown:unknown",
-                    status: "rejected",
-                    source: "invalid",
-                    createdAt: "",
-                    updatedAt: "",
-                    payload: { content: "" },
-                    review: {
-                        outcome: "rejected",
-                        reason: "Invalid proposal file (could not be parsed).",
-                        decidedAt: "",
-                    },
-                });
+                return false;
             }
-        }
-    }
-    return out
-        .filter((p) => (options.status ? p.status === options.status : true))
-        .filter((p) => (options.ref ? p.ref === options.ref : true))
-        .filter((p) => {
-        if (!options.type)
-            return true;
-        try {
-            return parseAssetRef(p.ref).type === options.type;
-        }
-        catch {
-            // Unparseable ref (e.g. the synthetic "unknown:unknown" stub for an
-            // invalid proposal file) never matches a concrete type filter.
-            return false;
-        }
-    })
-        .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        });
+    });
 }
 /**
- * Look up a proposal by id. Searches the live queue first, then the archive.
- * Throws `NotFoundError` when no match exists.
+ * Look up a proposal by id (live or archived).
+ * Throws `NotFoundError` when no match exists in this stash.
  */
-export function getProposal(stashDir, id) {
-    const livePath = proposalFile(stashDir, id, false);
-    if (fs.existsSync(livePath))
-        return readProposalFile(livePath);
-    const archivedPath = proposalFile(stashDir, id, true);
-    if (fs.existsSync(archivedPath))
-        return readProposalFile(archivedPath);
-    throw new NotFoundError(`Proposal "${id}" not found.`, "FILE_NOT_FOUND");
+export function getProposal(stashDir, id, ctx) {
+    return withProposalsDb(stashDir, ctx, (db) => requireProposal(db, stashDir, id));
+}
+function requireProposal(db, stashDir, id) {
+    const proposal = getStateProposal(db, id, stashDir);
+    if (!proposal) {
+        throw new NotFoundError(`Proposal "${id}" not found.`, "FILE_NOT_FOUND");
+    }
+    return proposal;
 }
 /**
  * Resolve a proposal by full UUID, UUID prefix, or asset ref.
@@ -425,95 +479,85 @@ export function getProposal(stashDir, id) {
  *   1. Exact UUID match (existing behaviour).
  *   2. Asset ref (contains `:`) — finds the most-recent pending proposal for
  *      that ref; falls back to archived if nothing is pending.
- *   3. UUID prefix — matches any live proposal directory whose name starts
- *      with the given string; throws if ambiguous.
+ *   3. UUID prefix — matches any PENDING proposal whose id starts with the
+ *      given string; throws if ambiguous.
  */
-export function resolveProposalId(stashDir, idOrRef) {
-    // 1. Exact UUID.
-    try {
-        return getProposal(stashDir, idOrRef);
-    }
-    catch (e) {
-        if (!(e instanceof NotFoundError))
-            throw e;
-    }
-    // 2. Asset ref (e.g. "skill:akm-dream").
-    if (idOrRef.includes(":")) {
-        const pending = listProposals(stashDir, { ref: idOrRef });
-        if (pending.length > 0) {
-            return pending.sort((a, b) => new Date(b.createdAt ?? 0).getTime() - new Date(a.createdAt ?? 0).getTime())[0];
+export function resolveProposalId(stashDir, idOrRef, ctx) {
+    return withProposalsDb(stashDir, ctx, (db) => {
+        // 1. Exact UUID.
+        const exact = getStateProposal(db, idOrRef, stashDir);
+        if (exact)
+            return exact;
+        // 2. Asset ref (e.g. "skill:akm-dream") — most recent pending, else most
+        // recent archived.
+        if (idOrRef.includes(":")) {
+            const byRecency = (proposals) => proposals.sort((a, b) => new Date(b.createdAt ?? 0).getTime() - new Date(a.createdAt ?? 0).getTime())[0];
+            const pending = byRecency(listStateProposals(db, { stashDir, ref: idOrRef, status: "pending" }));
+            if (pending)
+                return pending;
+            const archived = byRecency(listStateProposals(db, { stashDir, ref: idOrRef }));
+            if (archived)
+                return archived;
+            throw new NotFoundError(`No proposal found for ref "${idOrRef}".`, "FILE_NOT_FOUND");
         }
-        const archived = listProposals(stashDir, { ref: idOrRef, includeArchive: true });
-        if (archived.length > 0) {
-            return archived.sort((a, b) => new Date(b.createdAt ?? 0).getTime() - new Date(a.createdAt ?? 0).getTime())[0];
+        // 3. UUID prefix (pending queue only).
+        const prefixMatches = listStateProposalIdsByPrefix(db, stashDir, idOrRef);
+        if (prefixMatches.length === 1)
+            return requireProposal(db, stashDir, prefixMatches[0]);
+        if (prefixMatches.length > 1) {
+            throw new UsageError(`Ambiguous prefix "${idOrRef}" — matches: ${prefixMatches.join(", ")}`, "INVALID_FLAG_VALUE");
         }
-        throw new NotFoundError(`No proposal found for ref "${idOrRef}".`, "FILE_NOT_FOUND");
-    }
-    // 3. UUID prefix.
-    const liveDir = getProposalsRoot(stashDir, false);
-    let prefixMatches = [];
-    try {
-        prefixMatches = fs.readdirSync(liveDir).filter((name) => name.startsWith(idOrRef));
-    }
-    catch {
-        /* live dir may not exist yet */
-    }
-    if (prefixMatches.length === 1)
-        return getProposal(stashDir, prefixMatches[0]);
-    if (prefixMatches.length > 1) {
-        throw new UsageError(`Ambiguous prefix "${idOrRef}" — matches: ${prefixMatches.join(", ")}`, "INVALID_FLAG_VALUE");
-    }
-    throw new NotFoundError(`Proposal "${idOrRef}" not found.`, "FILE_NOT_FOUND");
+        throw new NotFoundError(`Proposal "${idOrRef}" not found.`, "FILE_NOT_FOUND");
+    });
 }
 /**
- * Whether a proposal currently lives in the archive (used by callers that
- * need to know whether to look in the archive root for files / paths).
+ * Archive a proposal: flip its status to `accepted` / `rejected`, bump
+ * `updatedAt`, and record the review block. Used by both accept and reject
+ * paths so the live queue only contains pending entries.
  */
-export function isProposalArchived(stashDir, id) {
-    return !fs.existsSync(proposalFile(stashDir, id, false)) && fs.existsSync(proposalFile(stashDir, id, true));
+export function archiveProposal(stashDir, id, status, reason, ctx) {
+    return withProposalsDb(stashDir, ctx, (db) => {
+        const existing = requireProposal(db, stashDir, id);
+        const updated = {
+            ...existing,
+            status,
+            updatedAt: nowIso(ctx),
+            review: {
+                outcome: status,
+                ...(reason !== undefined ? { reason } : {}),
+                decidedAt: nowIso(ctx),
+            },
+        };
+        upsertProposal(db, updated, stashDir);
+        return updated;
+    });
 }
 /**
- * Move a proposal directory into the archive subtree and update its status.
- * Used by both accept (status `accepted`) and reject (status `rejected`)
- * paths so the live queue only contains pending entries.
+ * Record an automated gate's decision onto a proposal (#577).
+ *
+ * Stamps `gateDecision` (decision / reason / confidence / thresholds) onto the
+ * row so `akm proposal show` and `list` can explain why a proposal landed where
+ * it did. The decision is metadata about the adjudication, so this does NOT
+ * change `status` or bump `updatedAt` — a `deferred` proposal stays `pending`,
+ * and the accept / reject status flips are owned by {@link promoteProposal} /
+ * {@link archiveProposal}. `decidedAt` defaults to now when the caller omits it.
+ *
+ * Best-effort: a proposal that no longer exists (e.g. concurrently archived) is
+ * skipped silently rather than throwing, so a gate run never aborts mid-batch.
+ * Returns the updated proposal, or undefined when no matching row exists.
  */
-export function archiveProposal(stashDir, id, status, reason, ctx) {
-    const sourceDir = proposalDir(stashDir, id, false);
-    if (!fs.existsSync(sourceDir)) {
-        // If it's already archived, just update the metadata in place.
-        const archived = proposalFile(stashDir, id, true);
-        if (fs.existsSync(archived)) {
-            const existing = readProposalFile(archived);
-            const updated = {
-                ...existing,
-                status,
-                updatedAt: nowIso(ctx),
-                review: {
-                    outcome: status,
-                    ...(reason !== undefined ? { reason } : {}),
-                    decidedAt: nowIso(ctx),
-                },
-            };
-            writeProposalFile(archived, updated);
-            return updated;
-        }
-        throw new NotFoundError(`Proposal "${id}" not found.`, "FILE_NOT_FOUND");
-    }
-    const targetDir = proposalDir(stashDir, id, true);
-    fs.mkdirSync(path.dirname(targetDir), { recursive: true });
-    fs.renameSync(sourceDir, targetDir);
-    const updated = {
-        ...readProposalFile(proposalFile(stashDir, id, true)),
-        status,
-        updatedAt: nowIso(ctx),
-        review: {
-            outcome: status,
-            ...(reason !== undefined ? { reason } : {}),
-            decidedAt: nowIso(ctx),
-        },
-    };
-    writeProposalFile(proposalFile(stashDir, id, true), updated);
-    return updated;
+export function recordGateDecision(stashDir, id, decision, ctx) {
+    return withProposalsDb(stashDir, ctx, (db) => {
+        const existing = getStateProposal(db, id, stashDir);
+        if (!existing)
+            return undefined;
+        const updated = {
+            ...existing,
+            gateDecision: { ...decision, decidedAt: decision.decidedAt ?? nowIso(ctx) },
+        };
+        upsertProposal(db, updated, stashDir);
+        return updated;
+    });
 }
 /**
  * Scan all pending proposals and reject those whose target asset no longer
@@ -529,7 +573,7 @@ export function purgeOrphanProposals(stashDir, sourceDirs, ctx) {
     const t0 = Date.now();
     const orphans = [];
     const byType = {};
-    const pending = listProposals(stashDir, { status: "pending" });
+    const pending = listProposals(stashDir, { status: "pending" }, ctx);
     const reflectPending = pending.filter((p) => p.source === "reflect");
     for (const p of reflectPending) {
         let parsed;
@@ -608,7 +652,7 @@ export function expireStaleProposals(stashDir, config, ctx) {
     }
     const retentionMs = retentionDays * MS_PER_DAY;
     const nowMs = (ctx?.now ?? Date.now)();
-    const pending = listProposals(stashDir, { status: "pending" });
+    const pending = listProposals(stashDir, { status: "pending" }, ctx);
     for (const p of pending) {
         const createdMs = new Date(p.createdAt).getTime();
         if (!Number.isFinite(createdMs))
@@ -658,18 +702,17 @@ export function validateProposal(proposal) {
 /**
  * Validate a proposal, then promote it through the canonical
  * {@link writeAssetToSource} dispatch (the single place that branches on
- * `source.kind`). On success the proposal directory is moved to the archive
- * with status `accepted`. Validation failures throw a `UsageError` carrying
- * every finding so the CLI can render a single clear error envelope.
+ * `source.kind`). On success the proposal is archived with status `accepted`.
+ * Validation failures throw a `UsageError` carrying every finding so the CLI
+ * can render a single clear error envelope.
  *
  * Phase 6C: when the target asset already exists at the resolved write path,
- * a snapshot of the prior content is captured under
- * `<proposalsRoot>/<id>/backup.<ext>` BEFORE the write. The relative path is
- * recorded on the proposal record (`backup` field) so `akm proposal revert`
- * can restore the prior content. Genuinely-new assets carry no backup.
+ * its prior content is captured BEFORE the write and stored on the archived
+ * proposal record (`backupContent`) so `akm proposal revert` can restore it.
+ * Genuinely-new assets carry no backup.
  */
 export async function promoteProposal(stashDir, config, id, options = {}, ctx) {
-    const proposal = getProposal(stashDir, id);
+    const proposal = getProposal(stashDir, id, ctx);
     if (proposal.status !== "pending") {
         throw new UsageError(`Proposal ${id} is not pending (current status: ${proposal.status}). Only pending proposals can be accepted.`, "INVALID_FLAG_VALUE");
     }
@@ -683,25 +726,15 @@ export async function promoteProposal(stashDir, config, id, options = {}, ctx) {
         throw new UsageError(`Proposal ${id} targets unknown asset type "${ref.type}".`, "INVALID_FLAG_VALUE");
     }
     const target = resolveWriteTarget(config, options.target);
-    // Phase 6C: capture a backup of the prior content (if any) BEFORE writing the
-    // new asset. We use the resolved write target to compute the exact path the
+    // Phase 6C: capture the prior content (if any) BEFORE writing the new
+    // asset. We use the resolved write target to compute the exact path the
     // asset would land at — same resolver `writeAssetToSource` uses — so the
     // backup always mirrors what would be overwritten.
-    let backupRelPath;
+    let backupContent;
     try {
         const targetFilePath = resolveAssetFilePathSafe(target.source, ref);
         if (targetFilePath && fs.existsSync(targetFilePath)) {
-            const ext = path.extname(targetFilePath) || ".md";
-            const proposalRoot = proposalDir(stashDir, id, false);
-            // Store relative path on the proposal record so the directory remains
-            // portable if the stash is moved.
-            const backupFilename = `backup${ext}`;
-            const backupAbsPath = path.join(proposalRoot, backupFilename);
-            fs.mkdirSync(proposalRoot, { recursive: true });
-            // Use copyFileSync — file-system atomicity is sufficient here because the
-            // backup is single-file and never read concurrently with this write.
-            fs.copyFileSync(targetFilePath, backupAbsPath);
-            backupRelPath = backupFilename;
+            backupContent = fs.readFileSync(targetFilePath, "utf8");
         }
     }
     catch (err) {
@@ -711,62 +744,58 @@ export async function promoteProposal(stashDir, config, id, options = {}, ctx) {
         warn(`[proposals] promoteProposal: failed to capture backup for ${id}: ${err instanceof Error ? err.message : String(err)}`);
     }
     const written = await writeAssetToSource(target.source, target.config, ref, proposal.payload.content);
+    // 0.9.0 (issue #507): single batch commit at the write boundary for git
+    // targets. No-op for filesystem/primary-stash targets.
+    commitWriteTargetBoundary(target, `Update ${formatRefForMessage(ref)}`);
     const archived = archiveProposal(stashDir, id, "accepted", undefined, ctx);
-    // Persist the backup path on the archived proposal record. archiveProposal
-    // moves the proposal dir into the archive subtree, so the backup file moves
-    // with it (the relative path stays valid).
-    if (backupRelPath) {
-        const archivedFile = proposalFile(stashDir, id, true);
-        const withBackup = { ...archived, backup: backupRelPath };
-        writeProposalFile(archivedFile, withBackup);
+    // Persist the backup content on the archived proposal record so the revert
+    // flow can restore the prior asset state.
+    if (backupContent !== undefined) {
+        const withBackup = { ...archived, backupContent };
+        withProposalsDb(stashDir, ctx, (db) => upsertProposal(db, withBackup, stashDir));
         return { proposal: withBackup, assetPath: written.path, ref: written.ref };
     }
     return { proposal: archived, assetPath: written.path, ref: written.ref };
 }
 /**
- * Restore the prior content of an accepted proposal from its captured backup
- * (Advantage D6c / Phase 6C).
+ * Restore the prior content of an accepted proposal from the backup captured
+ * at promotion time (Advantage D6c / Phase 6C).
  *
  * Pre-conditions:
  *   - `id` resolves to a proposal with `status === "accepted"`.
- *   - The proposal carries a `backup` field pointing to a readable file under
- *     the proposal directory.
+ *   - The proposal carries `backupContent` (captured by promoteProposal when
+ *     the target asset existed before the write).
  *
  * On success:
  *   - The backup content is written back through {@link writeAssetToSource},
  *     so the canonical write-dispatch invariant is preserved.
- *   - The archived proposal record is updated to `status: "reverted"`.
+ *   - The proposal record is updated to `status: "reverted"`.
  *   - Caller emits a `proposal_reverted` event in the CLI layer (mirrors how
  *     `promoted` / `rejected` are emitted by the CLI command, not the core).
  *
  * Errors are thrown as `UsageError` / `NotFoundError` so the CLI can map them
- * cleanly to exit codes — see `src/commands/proposal.ts` for the wrapper.
+ * cleanly to exit codes — see `src/commands/proposal/proposal.ts` for the
+ * wrapper.
  */
 export async function revertProposal(stashDir, config, id, options = {}, ctx) {
-    const proposal = getProposal(stashDir, id);
+    const proposal = getProposal(stashDir, id, ctx);
     if (proposal.status !== "accepted") {
         throw new UsageError(`only accepted proposals can be reverted (proposal ${id} status: ${proposal.status})`, "INVALID_FLAG_VALUE");
     }
-    if (!proposal.backup) {
+    if (proposal.backupContent === undefined) {
         throw new UsageError(`no backup available for this proposal (id: ${id})`, "MISSING_REQUIRED_ARGUMENT", "Backups are only captured when a proposal overwrites an existing asset — new-asset proposals cannot be reverted via this path; delete the asset directly instead.");
     }
-    // The proposal directory has been moved to the archive subtree (archiveProposal
-    // runs at the end of promoteProposal). Reads must resolve against that path.
-    const proposalRoot = proposalDir(stashDir, id, true);
-    const backupAbsPath = path.join(proposalRoot, proposal.backup);
-    if (!fs.existsSync(backupAbsPath)) {
-        throw new NotFoundError(`no backup available for this proposal (id: ${id})`, "FILE_NOT_FOUND", `Expected backup file at ${backupAbsPath}; it may have been removed manually.`);
-    }
-    const backupContent = fs.readFileSync(backupAbsPath, "utf8");
     const ref = parseAssetRef(proposal.ref);
     if (!TYPE_DIRS[ref.type]) {
         throw new UsageError(`Proposal ${id} targets unknown asset type "${ref.type}".`, "INVALID_FLAG_VALUE");
     }
     const target = resolveWriteTarget(config, options.target);
-    const written = await writeAssetToSource(target.source, target.config, ref, backupContent);
-    // Update the archived proposal record to status: "reverted" and bump
-    // updatedAt + review so the audit trail reflects the second decision.
-    const archivedFile = proposalFile(stashDir, id, true);
+    const written = await writeAssetToSource(target.source, target.config, ref, proposal.backupContent);
+    // 0.9.0 (issue #507): single batch commit at the write boundary for git
+    // targets. No-op for filesystem/primary-stash targets.
+    commitWriteTargetBoundary(target, `Revert ${formatRefForMessage(ref)}`);
+    // Update the proposal record to status: "reverted" and bump updatedAt +
+    // review so the audit trail reflects the second decision.
     const now = nowIso(ctx);
     const reverted = {
         ...proposal,
@@ -778,7 +807,7 @@ export async function revertProposal(stashDir, config, id, options = {}, ctx) {
             decidedAt: now,
         },
     };
-    writeProposalFile(archivedFile, reverted);
+    withProposalsDb(stashDir, ctx, (db) => upsertProposal(db, reverted, stashDir));
     return { proposal: reverted, assetPath: written.path, ref: written.ref };
 }
 /**
@@ -787,8 +816,8 @@ export async function revertProposal(stashDir, config, id, options = {}, ctx) {
  * diff matches exactly what `accept` will write. Falls back to "new asset"
  * when no asset is currently materialised at the target ref.
  */
-export function diffProposal(stashDir, config, id, options = {}) {
-    const proposal = getProposal(stashDir, id);
+export function diffProposal(stashDir, config, id, options = {}, ctx) {
+    const proposal = getProposal(stashDir, id, ctx);
     const ref = parseAssetRef(proposal.ref);
     let targetPath;
     let existing = null;