akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/core/proposals.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Proposal substrate (#225).
  *
@@ -33,15 +36,99 @@
  * that bypasses `writeAssetToSource` for "stash-adjacent" durable state. See
  * CLAUDE.md ("Writes" section) for the contract.
  */
-import { randomUUID } from "node:crypto";
+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 { parseFrontmatter } from "./frontmatter";
-import { lintLessonContent } from "./lesson-lint";
+import { appendEvent } from "./events";
+import { runProposalValidators } from "./proposal-validators";
+import { warn } from "./warn";
 import { resolveWriteTarget, writeAssetToSource } from "./write-source";
+// ── 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",
+    "improve",
+    // 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",
+    "improve",
+    "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");
+}
 // ── Path helpers ────────────────────────────────────────────────────────────
 /**
  * Resolve `<stashRoot>/.akm/proposals` (or its archive subdirectory). Direct
@@ -94,14 +181,140 @@ function writeProposalFile(filePath, proposal) {
 /**
  * Create a new pending proposal. The id is a stable random UUID, so two
  * proposals with the same `ref` never collide on disk.
+ *
+ * **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 to disk. Use {@link isProposalSkipped} to detect it.
  */
 export function createProposal(stashDir, input, ctx) {
-    // Validate the ref up front so callers get a clear error instead of a
-    // surprise during `accept`. This also normalises the ref string.
-    const parsedRef = parseAssetRef(input.ref);
+    // 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);
+    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 {
+                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 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,
+                };
+            }
+        }
+    }
     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,
@@ -114,6 +327,7 @@ export function createProposal(stashDir, input, ctx) {
             content: input.payload.content,
             ...(input.payload.frontmatter !== undefined ? { frontmatter: input.payload.frontmatter } : {}),
         },
+        ...(sanitizedConfidence !== undefined ? { confidence: sanitizedConfidence } : {}),
     };
     writeProposalFile(proposalFile(stashDir, id, false), proposal);
     return proposal;
@@ -158,7 +372,7 @@ export function listProposals(stashDir, options = {}) {
                 out.push({
                     id: entry.name,
                     ref: "unknown:unknown",
-                    status: "pending",
+                    status: "rejected",
                     source: "invalid",
                     createdAt: "",
                     updatedAt: "",
@@ -190,6 +404,53 @@ export function getProposal(stashDir, id) {
         return readProposalFile(archivedPath);
     throw new NotFoundError(`Proposal "${id}" not found.`, "FILE_NOT_FOUND");
 }
+/**
+ * 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 live proposal directory whose name 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];
+        }
+        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];
+        }
+        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");
+}
 /**
  * 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).
@@ -241,49 +502,144 @@ export function archiveProposal(stashDir, id, status, reason, ctx) {
     return updated;
 }
 /**
- * Validate a proposal payload before promotion. Generic by default — any
- * proposal must parse cleanly and carry a non-empty body. Lessons get the
- * extra per-type lint from {@link lintLessonContent} so the contract documented
- * in v1 spec §13 is enforced at promotion time. Other asset types can hook
- * here in the future without changing call sites.
+ * 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 validateProposal(proposal) {
-    const findings = [];
-    if (!proposal.payload || typeof proposal.payload.content !== "string" || proposal.payload.content.trim() === "") {
-        findings.push({ kind: "empty-content", message: `Proposal ${proposal.id} has empty content.` });
-    }
-    let ref;
-    try {
-        ref = parseAssetRef(proposal.ref);
-    }
-    catch (err) {
-        findings.push({
-            kind: "invalid-ref",
-            message: `Proposal ${proposal.id} has invalid ref "${proposal.ref}": ${err.message}`,
+export function purgeOrphanProposals(stashDir, sourceDirs, ctx) {
+    const t0 = Date.now();
+    const orphans = [];
+    const byType = {};
+    const pending = listProposals(stashDir, { status: "pending" });
+    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);
         });
-        return { ok: false, findings };
+        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)}`);
+            }
+        }
     }
-    // Generic frontmatter parse check for markdown-y types. If the content
-    // *looks* like it has frontmatter (`---\n…\n---`) we ensure it parses.
-    if (proposal.payload.content.startsWith("---")) {
+    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" });
+    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 {
-            parseFrontmatter(proposal.payload.content);
-        }
-        catch (err) {
-            findings.push({
-                kind: "invalid-frontmatter",
-                message: `Proposal ${proposal.id} frontmatter could not be parsed: ${err.message}`,
+            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,
+                },
             });
         }
-    }
-    // Type-specific validators.
-    if (ref.type === "lesson") {
-        const lessonReport = lintLessonContent(proposal.payload.content, `proposal:${proposal.id}`);
-        for (const finding of lessonReport.findings) {
-            findings.push({ kind: finding.kind, message: finding.message });
+        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 { ok: findings.length === 0, findings };
+    return {
+        checked: pending.length,
+        expired: expiredProposals.length,
+        durationMs: Date.now() - t0,
+        retentionDays,
+        expiredProposals,
+    };
+}
+/**
+ * Validate a proposal payload before promotion. Generic by default — any
+ * proposal must parse cleanly and carry a non-empty body. Lessons get the
+ * extra per-type lint from {@link lintLessonContent} so the contract documented
+ * in v1 spec §13 is enforced at promotion time. Other asset types can hook
+ * here in the future without changing call sites.
+ */
+export function validateProposal(proposal) {
+    return runProposalValidators(proposal);
 }
 /**
  * Validate a proposal, then promote it through the canonical
@@ -291,6 +647,12 @@ export function validateProposal(proposal) {
  * `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.
+ *
+ * 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.
  */
 export async function promoteProposal(stashDir, config, id, options = {}, ctx) {
     const proposal = getProposal(stashDir, id);
@@ -307,10 +669,104 @@ 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
+    // asset would land at — same resolver `writeAssetToSource` uses — so the
+    // backup always mirrors what would be overwritten.
+    let backupRelPath;
+    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;
+        }
+    }
+    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, proposal.payload.content);
     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);
+        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).
+ *
+ * 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.
+ *
+ * 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"`.
+ *   - 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.
+ */
+export async function revertProposal(stashDir, config, id, options = {}, ctx) {
+    const proposal = getProposal(stashDir, id);
+    if (proposal.status !== "accepted") {
+        throw new UsageError(`only accepted proposals can be reverted (proposal ${id} status: ${proposal.status})`, "INVALID_FLAG_VALUE");
+    }
+    if (!proposal.backup) {
+        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 now = nowIso(ctx);
+    const reverted = {
+        ...proposal,
+        status: "reverted",
+        updatedAt: now,
+        review: {
+            outcome: "rejected",
+            reason: "reverted: prior content restored from backup",
+            decidedAt: now,
+        },
+    };
+    writeProposalFile(archivedFile, reverted);
+    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