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

package/dist/commands/proposal/repository.js

@@ -0,0 +1,829 @@
+// 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/.
+/**
+ * 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 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
+ *
+ * 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.
+ *
+ * ## Legacy filesystem import
+ *
+ * Before 0.9.0 proposals lived as per-uuid JSON directories under
+ * `<stashDir>/.akm/proposals/`. The first proposal operation against a stash
+ * imports any legacy `proposal.json` files into the table — see
+ * `./legacy-import.ts` (`importLegacyProposalFiles`), funnelled through
+ * {@link withProposalsDb}.
+ *
+ * # Why the queue bypasses `writeAssetToSource`
+ *
+ * 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 "../../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 { withImmediateTransaction, withStateDb } from "../../core/state-db.js";
+import { warn } from "../../core/warn.js";
+import { commitWriteTargetBoundary, formatRefForMessage, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { getStateProposal, listStateProposalIdsByPrefix, listStateProposals, upsertProposal, } from "../../storage/repositories/proposals-repository.js";
+import { importLegacyProposalFiles } from "./legacy-import.js";
+import { repairProposalContent, validateProposal } from "./validators/proposals.js";
+// ── Source allow-list (F-4 / #385) ──────────────────────────────────────────
+/**
+ * Curated allow-list of valid `source` values for proposals (F-4 / #385).
+ *
+ * Rationale (W3C PROV-DM 2013): Provenance records require typed, validated
+ * sources for meaningful aggregation. Accept-rate-per-source is the core
+ * self-measurement metric for recursive self-improvement: if reflect proposals
+ * are accepted at 20% and distill proposals at 60%, that guides resource
+ * allocation. Free-text typos (`"reflct"`) produce unaggregatable events.
+ *
+ * Automated sources (those in {@link AUTOMATED_PROPOSAL_SOURCES}) require a
+ * `sourceRun` field for full PROV-DM traceability.
+ */
+export const PROPOSAL_SOURCES = [
+    // Automated sources — require sourceRun for traceability.
+    "reflect",
+    "distill",
+    "consolidate",
+    "extract",
+    "improve",
+    "recombine",
+    "procedural",
+    // Semi-automated / tool-driven.
+    "feedback",
+    // Human-initiated / CLI-driven.
+    "propose",
+    "remember",
+    "import",
+    // Internal / system.
+    "distill_quality_rejected",
+    "schema-repair",
+];
+/** Automated sources that SHOULD include a `sourceRun` for PROV-DM traceability. */
+export const AUTOMATED_PROPOSAL_SOURCES = [
+    "reflect",
+    "distill",
+    "consolidate",
+    "extract",
+    "improve",
+    "recombine",
+    "procedural",
+    "schema-repair",
+];
+/**
+ * Check whether a string is a valid {@link ProposalSource}.
+ * Unknown source values are accepted with a runtime warning rather than a hard
+ * error, to allow extensions without breaking existing callers.
+ */
+export function isValidProposalSource(source) {
+    return PROPOSAL_SOURCES.includes(source);
+}
+/**
+ * Check whether a source value is an automated source requiring `sourceRun`.
+ */
+export function isAutomatedProposalSource(source) {
+    return AUTOMATED_PROPOSAL_SOURCES.includes(source);
+}
+/** Type guard: true when createProposal returned a skipped record. */
+export function isProposalSkipped(result) {
+    return result.skipped === true;
+}
+// ── Dedup / cooldown constants ───────────────────────────────────────────────
+const MS_PER_DAY = 86_400_000;
+/**
+ * Post-rejection cooldown windows by source. After a proposal is rejected,
+ * `createProposal` silently skips new proposals for the same `ref+source`
+ * until the window expires (unless `force: true` is passed).
+ *
+ * Rationale (Settles 2009 active-learning survey; Argilla/Label Studio HITL):
+ * Reviewer fatigue is a blocker for the human-in-the-loop guarantee. Cooldowns
+ * prevent nightly improve runs from re-flooding the queue with near-identical
+ * proposals the reviewer just declined.
+ *
+ *   - reflect: 14 days (agent-based; slower feedback loops)
+ *   - distill: 30 days (LLM-based; even more prone to regeneration loops)
+ *   - default: 7 days  (conservative fallback for other sources)
+ */
+const COOLDOWN_MS = {
+    reflect: 14 * MS_PER_DAY,
+    distill: 30 * MS_PER_DAY,
+};
+const DEFAULT_COOLDOWN_MS = 7 * MS_PER_DAY;
+function cooldownMsForSource(source) {
+    return COOLDOWN_MS[source] ?? DEFAULT_COOLDOWN_MS;
+}
+/** Compute a stable SHA-256 hex digest of a proposal's content string. */
+function contentHash(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+// ── Store access ─────────────────────────────────────────────────────────────
+function nowIso(ctx) {
+    const fn = ctx?.now ?? Date.now;
+    return new Date(fn()).toISOString();
+}
+function newId(ctx) {
+    const fn = ctx?.randomUUID ?? randomUUID;
+    return fn();
+}
+/**
+ * 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) {
+    return withStateDb((db) => {
+        importLegacyProposalFiles(db, stashDir);
+        return fn(db);
+    }, { path: ctx?.dbPath });
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Create a new pending proposal. The id is a stable random UUID, so two
+ * proposals with the same `ref` never collide.
+ *
+ * **Dedup / cooldown guard** (F-2 / #363):
+ *
+ * Before writing, this function checks:
+ *   1. `duplicate_pending` — a pending proposal already exists for the same
+ *      `ref+source`. Pass `input.force = true` to bypass.
+ *   2. `content_hash_match` — an identical content hash is already pending or
+ *      was recently rejected for this `ref+source`. Bypass with `force: true`.
+ *   3. `cooldown` — a proposal for this `ref+source` was rejected within the
+ *      source-specific cooldown window (reflect: 14 d, distill: 30 d,
+ *      others: 7 d). Bypass with `force: true`.
+ *
+ * When a guard fires the function returns a `CreateProposalSkipped` record
+ * 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
+    // warned (not rejected) for backward compatibility — extension callers
+    // that pass custom source strings must not break.
+    if (!isValidProposalSource(input.source)) {
+        warn(`[proposal] Unknown source "${input.source}". ` +
+            `Expected one of: ${PROPOSAL_SOURCES.join(", ")}. ` +
+            "Typos in source values produce unaggregatable accept-rate-per-source metrics.");
+    }
+    else if (isAutomatedProposalSource(input.source) && !input.sourceRun) {
+        // Advisory warning: automated sources should include sourceRun for PROV-DM
+        // traceability. This is not a hard error to avoid breaking existing callers.
+        warn(`[proposal] Automated source "${input.source}" created a proposal without sourceRun. ` +
+            "Add sourceRun to enable accept-rate-per-run aggregation (W3C PROV-DM).");
+    }
+    // Deterministic input validation. Reject obviously-invalid proposals at
+    // the source rather than letting them enter the queue and waste reviewer
+    // time. Each rejection emits `proposal_creation_rejected` with a typed
+    // reason so we can see *which* check is firing in the event stream.
+    const rejectProposal = (reason, message) => {
+        appendEvent({
+            eventType: "proposal_creation_rejected",
+            ref: input.ref,
+            metadata: { source: input.source, reason },
+        });
+        throw new UsageError(message, "INVALID_PROPOSAL");
+    };
+    let parsedRef;
+    try {
+        parsedRef = parseAssetRef(input.ref);
+    }
+    catch (err) {
+        return rejectProposal("invalid_ref", `Invalid proposal ref "${input.ref}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!TYPE_DIRS[parsedRef.type]) {
+        return rejectProposal("unknown_type", `Unknown asset type "${parsedRef.type}" in proposal ref "${input.ref}". Known types: ${Object.keys(TYPE_DIRS).sort().join(", ")}.`);
+    }
+    if (!input.payload.content.trim()) {
+        return rejectProposal("empty_content", `Proposal for "${input.ref}" has empty content.`);
+    }
+    // Description check is only enforced for `consolidate` source — that's the
+    // automated pipeline that historically produced proposals with missing or
+    // malformed frontmatter, polluting the queue with hundreds of unusable
+    // entries. Reflect / distill / propose proposals have varied legitimate
+    // shapes and should not be rejected here for missing description.
+    if (input.source === "consolidate") {
+        const desc = input.payload.frontmatter?.description;
+        if (typeof desc !== "string" || desc.trim() === "") {
+            return rejectProposal("missing_description", `Proposal for "${input.ref}" (source=consolidate) has empty or missing frontmatter description.`);
+        }
+    }
+    const normalizedRef = makeAssetRef(parsedRef.type, parsedRef.name, parsedRef.origin);
+    return withProposalsDb(stashDir, ctx, (db) => {
+        return withImmediateTransaction(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 } : {}),
+                // Attribution tagging: persist the eligibility lane so it survives to
+                // accept/reject/revert time. See EligibilitySource.
+                ...(input.eligibilitySource !== undefined ? { eligibilitySource: input.eligibilitySource } : {}),
+            };
+            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: "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 {
+            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,
+            };
+        }
+    }
+    return undefined;
+}
+/**
+ * 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 = {}, 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 [];
+        }
+        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 {
+                return parseAssetRef(p.ref).type === options.type;
+            }
+            catch {
+                return false;
+            }
+        });
+    });
+}
+/**
+ * Look up a proposal by id (live or archived).
+ * Throws `NotFoundError` when no match exists in this stash.
+ */
+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.
+ *
+ * Resolution order:
+ *   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 PENDING proposal whose id starts with the
+ *      given string; throws if ambiguous.
+ */
+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");
+        }
+        // 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(`Proposal "${idOrRef}" not found.`, "FILE_NOT_FOUND");
+    });
+}
+/**
+ * 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 archiveProposal(stashDir, id, status, reason, ctx) {
+    return withProposalsDb(stashDir, ctx, (db) => {
+        return withImmediateTransaction(db, () => {
+            const existing = requireProposal(db, stashDir, id);
+            if (existing.status !== "pending") {
+                throw new UsageError(`Proposal ${id} is not pending (current status: ${existing.status}). Only pending proposals can be ${status}.`, "INVALID_FLAG_VALUE");
+            }
+            const decidedAt = nowIso(ctx);
+            const updated = {
+                ...existing,
+                status,
+                updatedAt: decidedAt,
+                review: {
+                    outcome: status,
+                    ...(reason !== undefined ? { reason } : {}),
+                    decidedAt,
+                },
+            };
+            upsertProposal(db, updated, stashDir);
+            return updated;
+        });
+    });
+}
+/**
+ * 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 recordGateDecision(stashDir, id, decision, ctx) {
+    return withProposalsDb(stashDir, ctx, (db) => {
+        return withImmediateTransaction(db, () => {
+            const existing = getStateProposal(db, id, stashDir);
+            if (!existing || existing.status !== "pending")
+                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
+ * exists on disk across any of `sourceDirs`. Intended to run as a periodic
+ * maintenance pass (see `runImproveMaintenancePasses`) — it keeps the queue
+ * from accumulating stale reviewer work after large refactors or deletes.
+ *
+ * Scope rule: only `source=reflect` proposals are subject to orphan rejection.
+ * Lessons, propose, distill, and consolidate proposals legitimately target
+ * assets that don't exist yet and must never be purged.
+ */
+export function purgeOrphanProposals(stashDir, sourceDirs, ctx) {
+    const t0 = Date.now();
+    const orphans = [];
+    const byType = {};
+    const pending = listProposals(stashDir, { status: "pending" }, ctx);
+    const reflectPending = pending.filter((p) => p.source === "reflect");
+    for (const p of reflectPending) {
+        let parsed;
+        try {
+            parsed = parseAssetRef(p.ref);
+        }
+        catch {
+            continue;
+        }
+        // Lessons are new-asset proposals by definition — they cannot be orphaned.
+        if (parsed.type === "lesson")
+            continue;
+        const spec = TYPE_DIRS[parsed.type];
+        if (!spec)
+            continue;
+        const exists = sourceDirs.some((root) => {
+            const typeRoot = path.join(root, spec);
+            const candidate = resolveAssetPathFromName(parsed.type, typeRoot, parsed.name);
+            return fs.existsSync(candidate);
+        });
+        if (!exists) {
+            try {
+                archiveProposal(stashDir, p.id, "rejected", "Asset no longer exists on disk", ctx);
+                orphans.push({ id: p.id, ref: p.ref, reason: "asset_missing" });
+                byType[parsed.type] = (byType[parsed.type] ?? 0) + 1;
+            }
+            catch (err) {
+                // Best-effort — the purge is non-fatal. Log and continue.
+                warn(`[proposals] purgeOrphanProposals: failed to reject ${p.id}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    return {
+        checked: reflectPending.length,
+        rejected: orphans.length,
+        durationMs: Date.now() - t0,
+        byType,
+        orphans,
+    };
+}
+/**
+ * Archive pending proposals older than `config.archiveRetentionDays` (Advantage
+ * D6b / Phase 6B).
+ *
+ * Reviewer fatigue and queue rot are the dominant failure modes of any
+ * human-in-the-loop pipeline (Settles 2009 active-learning survey). Pending
+ * proposals that have aged past the retention window are very rarely accepted
+ * — the reviewer either intentionally declined to act on them, or the asset
+ * they target has drifted enough that the proposal is no longer relevant.
+ * Auto-expiring them keeps the live queue focused on actionable work; the
+ * archive preserves the full audit trail.
+ *
+ * Each expired proposal is archived with status `rejected` and reason
+ * `"expired: no action within retention window"`. A `proposal_expired` event
+ * is appended for each expired proposal so downstream observability (events
+ * dashboards, source-acceptance-rate aggregations) can see expiry separately
+ * from explicit rejections.
+ *
+ * Idempotent: a second call within the same retention window finds nothing
+ * to expire (the archived entries are no longer in the pending queue).
+ */
+export function expireStaleProposals(stashDir, config, ctx) {
+    const t0 = Date.now();
+    const retentionDays = config.archiveRetentionDays ?? 90;
+    const expiredProposals = [];
+    // retentionDays === 0 disables TTL cleanup globally (mirrors how
+    // consolidate.ts interprets the same config value).
+    if (retentionDays <= 0) {
+        return {
+            checked: 0,
+            expired: 0,
+            durationMs: Date.now() - t0,
+            retentionDays,
+            expiredProposals,
+        };
+    }
+    const retentionMs = retentionDays * MS_PER_DAY;
+    const nowMs = (ctx?.now ?? Date.now)();
+    const pending = listProposals(stashDir, { status: "pending" }, ctx);
+    for (const p of pending) {
+        const createdMs = new Date(p.createdAt).getTime();
+        if (!Number.isFinite(createdMs))
+            continue;
+        const ageMs = nowMs - createdMs;
+        if (ageMs < retentionMs)
+            continue;
+        try {
+            archiveProposal(stashDir, p.id, "rejected", "expired: no action within retention window", ctx);
+            const ageDays = Math.floor(ageMs / MS_PER_DAY);
+            expiredProposals.push({ id: p.id, ref: p.ref, ageDays });
+            appendEvent({
+                eventType: "proposal_expired",
+                ref: p.ref,
+                metadata: {
+                    proposalId: p.id,
+                    source: p.source,
+                    ...(p.sourceRun !== undefined ? { sourceRun: p.sourceRun } : {}),
+                    ageDays,
+                    retentionDays,
+                },
+            });
+        }
+        catch (err) {
+            // Best-effort — a single failure must not block the pass.
+            warn(`[proposals] expireStaleProposals: failed to expire ${p.id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return {
+        checked: pending.length,
+        expired: expiredProposals.length,
+        durationMs: Date.now() - t0,
+        retentionDays,
+        expiredProposals,
+    };
+}
+/**
+ * Validate a proposal, then promote it through the canonical
+ * {@link writeAssetToSource} dispatch (the single place that branches on
+ * `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,
+ * 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, 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");
+    }
+    // Attempt bounded auto-repair of mechanically-fixable structural defects
+    // (pseudo-frontmatter-in-body, stray `---` fences, truncated description)
+    // BEFORE running validation. If the repair produces valid content, we
+    // promote the repaired version; if validation still fails, the original
+    // error path throws as before. The repair is content-preserving and
+    // deterministic — it never invents text.
+    const repairedContent = repairProposalContent(proposal.payload.content);
+    const proposalToValidate = repairedContent !== proposal.payload.content
+        ? { ...proposal, payload: { ...proposal.payload, content: repairedContent } }
+        : proposal;
+    const report = validateProposal(proposalToValidate);
+    if (!report.ok) {
+        const message = report.findings.map((f) => `[${f.kind}] ${f.message}`).join("\n");
+        throw new UsageError(`Proposal ${id} failed validation:\n${message}`, "MISSING_REQUIRED_ARGUMENT", "Fix the proposal payload (frontmatter / content) and try again, or reject the proposal with a reason.");
+    }
+    // Use the (possibly repaired) payload for the promotion write. Persist the
+    // repaired content back onto the DB row so the audit trail reflects the
+    // final promoted payload (not the defective original).
+    if (repairedContent !== proposal.payload.content) {
+        withProposalsDb(stashDir, ctx, (db) => {
+            const updated = { ...proposal, payload: { ...proposal.payload, content: repairedContent } };
+            upsertProposal(db, updated, stashDir);
+        });
+    }
+    const ref = parseAssetRef(proposalToValidate.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);
+    // 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 backupContent;
+    try {
+        const targetFilePath = resolveAssetFilePathSafe(target.source, ref);
+        if (targetFilePath && fs.existsSync(targetFilePath)) {
+            backupContent = fs.readFileSync(targetFilePath, "utf8");
+        }
+    }
+    catch (err) {
+        // Backup capture is best-effort. A failure here must not block promotion
+        // (the user explicitly asked to accept); we surface a warning so the
+        // missing-revert path is visible.
+        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, repairedContent);
+    // 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 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 the backup captured
+ * at promotion time (Advantage D6c / Phase 6C).
+ *
+ * Pre-conditions:
+ *   - `id` resolves to a proposal with `status === "accepted"`.
+ *   - 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 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/proposal.ts` for the
+ * wrapper.
+ */
+export async function revertProposal(stashDir, config, id, options = {}, ctx) {
+    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.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.");
+    }
+    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, 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,
+        status: "reverted",
+        updatedAt: now,
+        review: {
+            outcome: "rejected",
+            reason: "reverted: prior content restored from backup",
+            decidedAt: now,
+        },
+    };
+    withProposalsDb(stashDir, ctx, (db) => upsertProposal(db, reverted, stashDir));
+    return { proposal: reverted, assetPath: written.path, ref: written.ref };
+}
+/**
+ * Compute a diff between a proposal payload and the existing on-disk asset.
+ * Uses {@link resolveWriteTarget} to find where the asset would land — so the
+ * 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 = {}, ctx) {
+    const proposal = getProposal(stashDir, id, ctx);
+    const ref = parseAssetRef(proposal.ref);
+    let targetPath;
+    let existing = null;
+    try {
+        const target = resolveWriteTarget(config, options.target);
+        targetPath = resolveAssetFilePathSafe(target.source, ref);
+        if (targetPath && fs.existsSync(targetPath)) {
+            existing = fs.readFileSync(targetPath, "utf8");
+        }
+    }
+    catch {
+        // No writable target configured — still return a "new asset" diff so
+        // callers can see the proposed payload without erroring out.
+    }
+    const proposed = proposal.payload.content;
+    if (existing === null) {
+        return {
+            existing: null,
+            proposed,
+            unified: formatNewAssetDiff(proposal.ref, proposed),
+            isNew: true,
+            ...(targetPath ? { targetPath } : {}),
+        };
+    }
+    return {
+        existing,
+        proposed,
+        unified: formatUnifiedDiff(existing, proposed, proposal.ref),
+        isNew: false,
+        ...(targetPath ? { targetPath } : {}),
+    };
+}
+function resolveAssetFilePathSafe(source, ref) {
+    const typeDir = TYPE_DIRS[ref.type];
+    if (!typeDir)
+        return undefined;
+    const typeRoot = path.join(source.path, typeDir);
+    try {
+        return resolveAssetPathFromName(ref.type, typeRoot, ref.name);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Minimal unified-diff renderer. We deliberately avoid pulling a runtime
+ * dependency just for this — proposals diffs are usually small (a single
+ * lesson / skill file), so the LCS-free greedy renderer below is plenty for
+ * humans to review. The output mirrors `git diff --no-index` for the first
+ * `@@ … @@` hunk: enough to be familiar, not so detailed that we re-implement
+ * a full LCS table.
+ */
+export function formatUnifiedDiff(left, right, label) {
+    if (left === right)
+        return "";
+    const leftLines = left.split("\n");
+    const rightLines = right.split("\n");
+    const lines = [`--- ${label} (existing)`, `+++ ${label} (proposed)`];
+    // Pad to the longer side so alignment is one-to-one. Real diff tools use
+    // LCS to align matching runs; we don't need that fidelity for a review
+    // surface — both halves are visible regardless.
+    const max = Math.max(leftLines.length, rightLines.length);
+    lines.push(`@@ 1,${leftLines.length} 1,${rightLines.length} @@`);
+    for (let i = 0; i < max; i += 1) {
+        const l = leftLines[i];
+        const r = rightLines[i];
+        if (l === r && l !== undefined) {
+            lines.push(` ${l}`);
+            continue;
+        }
+        if (l !== undefined)
+            lines.push(`-${l}`);
+        if (r !== undefined)
+            lines.push(`+${r}`);
+    }
+    return lines.join("\n");
+}
+function formatNewAssetDiff(ref, content) {
+    const lines = [`--- /dev/null`, `+++ ${ref} (proposed, new asset)`];
+    lines.push(`@@ 0,0 1,${content.split("\n").length} @@`);
+    for (const line of content.split("\n")) {
+        lines.push(`+${line}`);
+    }
+    return lines.join("\n");
+}