akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/commands/proposal/repository.js

@@ -21,17 +21,6 @@
  * 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/`. That import used to run on EVERY proposal
- * operation here (through {@link withProposalsDb}, disk-probing the legacy tree
- * forever). It has been FOLDED OUT of the live path into the one-time migrator:
- * `akm migrate apply` runs it once as an additive step (see
- * `src/migrate/legacy/proposal-fs-import.ts`). Idempotency is now INSERT OR
- * IGNORE on the proposal UUID plus migrate-apply's own journal — no live-path
- * probe, no `proposal_fs_imports` ledger.
- *
  * # Why the queue bypasses `writeAssetToSource`
  *
  * The architectural rule "all writes go through `writeAssetToSource`" applies
@@ -45,27 +34,40 @@
  */
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { adapterForId } from "../../core/adapter/registry.js";
+import { createValidateContext } from "../../core/adapter/validate-context.js";
+import { ensureAkmMarkdownType } from "../../core/asset/akm-markdown.js";
 import { assetPathForName, placementTypes, stashDirFor } from "../../core/asset/asset-placement.js";
-import { isBundleSlug } from "../../core/asset/asset-ref.js";
+import { isBundleSlug, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { assembleAsset, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { isWithin } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
-import { NotFoundError, UsageError } from "../../core/errors.js";
+import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { proposalContent } from "../../core/file-change.js";
-import { _setTxnMutationHookForTests, advanceTxn, beginTxn, canonicalTxnRoot, cleanupTxn, fsyncTxnDir, fsyncTxnFile, listTxnJournals, mintTxnId, recoverTxnsForRoot, registerTxnKind, sweepJournallessTxnDir, txnDirFor, txnMutationHook, txnNamespaceDir, } from "../../core/fs-txn.js";
+import { _setTxnMutationHookForTests, advanceTxn, beginTxn, canonicalTxnRoot, cleanupTxn, fsyncTxnDir, fsyncTxnFile, listTxnJournals, mintTxnId, registerTxnKind, sweepJournallessTxnDir, txnDirFor, txnMutationHook, txnNamespaceDir, } from "../../core/fs-txn.js";
+import { canonicalBundleIdForTarget, resolveBundleWriteTarget } from "../../core/mutation-target.js";
 import { withImmediateTransaction, withStateDb } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
-import { commitWriteTargetBoundary, resolveWritableTargets, resolveWriteTarget, } from "../../core/write-source.js";
+import { assertAkmAssetWrite, assertWriteTargetPathsClean, captureGitPublication, captureWriteTargetPathSnapshot, prepareWriteTargetForMutation, publishWriteTargetTransaction, resolveWriteTarget, } from "../../core/write-source.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
-import { deriveInstallations, slugForPath } from "../../indexer/installations.js";
+import { deriveInstallations } from "../../indexer/installations.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertEventOnce } from "../../storage/repositories/events-repository.js";
-import { getStateProposal, listStateProposalIdsByPrefix, listStateProposals, upsertProposal, } from "../../storage/repositories/proposals-repository.js";
+import { getStateProposal, getStateProposalLenient, listStateProposalIdsByPrefix, listStateProposals, upsertProposal, } from "../../storage/repositories/proposals-repository.js";
+import { pkgVersion } from "../../version.js";
+import { runBaseChecks } from "../lint/base-linter.js";
 import { formatNewAssetDiff, formatUnifiedDiff } from "./diff-format.js";
 import { isAutomatedProposalSource, isValidProposalSource, PROPOSAL_SOURCES, } from "./proposal-types.js";
+import { hasCanonicalProposalValidator } from "./validators/proposal-validators.js";
 import { repairProposalContent, validateProposal } from "./validators/proposals.js";
+const PROMOTION_LINT_BLOCKERS = new Set(["unquoted-colon", "missing-ref", "stale-path"]);
 // ── Proposal domain types (moved to ./proposal-types.ts, WI-9.8 KILL 1) ─────
 //
 // Proposal / ProposalStatus / ProposalPayload / ProposalReview /
@@ -73,8 +75,8 @@ import { repairProposalContent, validateProposal } from "./validators/proposals.
 // AUTOMATED_PROPOSAL_SOURCES / isValidProposalSource / isAutomatedProposalSource
 // moved to the dependency-free leaf so validators/proposals.ts,
 // validators/proposal-validators.ts, storage/repositories/proposals-repository.ts,
-// and legacy-import.ts can import the `Proposal` type without importing this
-// (much heavier) txn-engine module back — that back-edge was the
+// and storage repositories can import the `Proposal` type without importing
+// this heavier transaction-engine module back. That back-edge was the
 // repository↔validators import cycle (plan §10.7 D.3). Every symbol this
 // module used to export directly is re-exported here verbatim so existing
 // import sites (`from "../proposal/repository.js"`) are unchanged.
@@ -92,7 +94,7 @@ function withProposalContent(p, content) {
     return {
         ...p,
         payload: { ...p.payload, content },
-        changes: (p.changes ?? [{ path: "", op: "update" }]).map((c, i) => 
+        changes: p.changes.map((c, i) => 
         // A delete-op primary change carries no `after` (file-change.ts contract).
         i === 0 && c.op !== "delete" ? { ...c, after: content } : c),
     };
@@ -144,81 +146,138 @@ function newId(ctx) {
  * connection to `fn`, and close it in a `finally`. Every public function in
  * this module funnels its store access through here.
  *
- * The pre-0.9 filesystem-proposal import no longer runs here — it was a per-op
- * disk probe of `<stashDir>/.akm/proposals/` and now runs once inside
- * `akm migrate apply` (`src/migrate/legacy/proposal-fs-import.ts`). `stashDir`
- * is still threaded through the public API for the store's per-stash partition.
+ * `stashDir` is threaded through the public API for the store's per-stash
+ * partition.
  */
 function withProposalsDb(_stashDir, ctx, fn) {
     return withStateDb(fn, { path: ctx?.dbPath });
 }
-/**
- * WI-8.5a — the durable `proposals.ref` key in the final `bundle//conceptId`
- * item_ref grammar (D-R3). The conceptId is BUILT from the D-R2 static table
- * ({@link conceptIdFromTypeName} = `<stash-subdir>/<name>`), never looked up, so a
- * proposal targeting a not-yet-existing asset (no index entry) still keys onto
- * its final spelling. The bundle is the write-target stash's installation id —
- * the SAME `deriveInstallations` derivation the index write path uses
- * (`index-written-assets.ts`), so a proposal's ref matches the item_ref the
- * indexer would mint for the accepted asset byte-for-byte.
- *
- * A proposal carrying a slug-clean registry origin re-keys onto that bundle; a
- * non-slug registry origin (`github:owner/repo`, `npm:@scope/pkg`) cannot be
- * re-keyed without inventing a slug (D-R5) and keeps its legacy
- * `origin//type:name` spelling until the config `bundles` key lands. The
- * `local`/`stash` primary-stash sentinels resolve to the write-target bundle.
- */
-/**
- * The conceptId (`<stash-subdir>/<name>`) a STORED proposal ref maps to
- * (`undefined` when unparseable). TOLERANT by design: a single malformed durable
- * row must never crash a listing, so a parse failure here degrades to "no match"
- * rather than throwing. WI-8.5a stores `proposals.ref` as the item_ref, so a
- * user query ref (`lessons/x` / `bundle//lessons/x`) can no longer exact-match
- * the stored `bundle//lessons/x`; matching on the shared conceptId is the durable
- * read for the user-facing filter paths (`proposal list --ref`,
- * `resolveProposalId`). The internal fingerprint/backoff paths keep exact
- * `ref`-column matching (they compare the already-final `normalizedRef`), so old
- * legacy rejected rows aging out is the documented dedup-window reset, not a
- * lookup regression.
- *
- * USER-SUPPLIED filter refs go through {@link filterConceptId} instead — an
- * unparseable filter is a loud usage error, never a silent empty result.
- */
-function proposalConceptId(ref) {
+function persistProposalUpdate(db, proposal, stashDir) {
+    // Only take the full re-serialize (upsertProposal -> proposalToRowValues)
+    // path when `changes` is well-formed enough to survive it — a non-empty
+    // path on every entry, matching proposalToRowValues' own validation. A
+    // legacy row with a present `proposedTarget` but an empty/missing
+    // `changes[].path` (e.g. a malformed 0.8-era row) would otherwise die in
+    // proposalToRowValues; falling through to the targeted UPDATE below keeps
+    // `changes`/`proposedTarget` untouched in metadata_json and only flips the
+    // status/review/etc. fields the terminal transition actually needs.
+    const changesAreWellFormed = proposal.changes.length > 0 && proposal.changes.every((change) => change.path.length > 0);
+    if (changesAreWellFormed && proposal.proposedTarget) {
+        upsertProposal(db, proposal, stashDir);
+        return;
+    }
+    const row = db
+        .prepare("SELECT metadata_json FROM proposals WHERE id = ? AND stash_dir = ?")
+        .get(proposal.id, stashDir);
+    if (!row)
+        throw new NotFoundError(`Proposal "${proposal.id}" not found.`, "PROPOSAL_NOT_FOUND");
+    const metadata = JSON.parse(row.metadata_json);
+    for (const field of [
+        "sourceRun",
+        "beforeHash",
+        "review",
+        "confidence",
+        "gateDecision",
+        "backupContent",
+        "acceptedTarget",
+        "eligibilitySource",
+    ]) {
+        const value = proposal[field];
+        if (value === undefined)
+            delete metadata[field];
+        else
+            metadata[field] = value;
+    }
+    db.prepare(`UPDATE proposals
+     SET ref = ?, status = ?, source = ?, updated_at = ?, content = ?, frontmatter_json = ?, metadata_json = ?
+     WHERE id = ? AND stash_dir = ?`).run(proposal.ref, proposal.status, proposal.source, proposal.updatedAt, proposal.payload.content, proposal.payload.frontmatter ? JSON.stringify(proposal.payload.frontmatter) : null, JSON.stringify(metadata), proposal.id, stashDir);
+}
+function proposalRefIdentity(ref) {
     try {
-        const p = parseRefInput(ref);
-        return conceptIdFromTypeName(p.type, p.name);
+        const parsed = parseBundleRef(ref);
+        if (parsed.fragment !== undefined || isRetiredProposalConceptId(parsed.conceptId))
+            return undefined;
+        return {
+            conceptId: parsed.conceptId,
+            ...(parsed.bundle !== undefined ? { bundle: parsed.bundle } : {}),
+        };
     }
     catch {
         return undefined;
     }
 }
-/**
- * The conceptId a USER-SUPPLIED `--ref` / `idOrRef` filter maps to. Unlike the
- * tolerant {@link proposalConceptId} (which reads STORED rows), an unparseable
- * filter throws a typed {@link UsageError} rather than resolving to `undefined`
- * and silently matching nothing — an invalid filter should fail loudly, naming
- * the 0.9.0 grammar (D-R3: the legacy `type:name` grammar is gone). Delegates the
- * grammar to `parseRefInput`, so a legacy `skill:x` input surfaces the same loud
- * error as any other unparseable filter.
- */
-function filterConceptId(ref) {
+function filterRefIdentity(ref) {
     try {
-        const p = parseRefInput(ref);
-        return conceptIdFromTypeName(p.type, p.name);
+        const p = parseBundleRef(ref);
+        if (p.fragment !== undefined || isRetiredProposalConceptId(p.conceptId)) {
+            throw new Error("not a current proposal identity");
+        }
+        return {
+            conceptId: p.conceptId,
+            ...(p.bundle !== undefined ? { bundle: p.bundle } : {}),
+        };
     }
     catch {
         throw new UsageError(`Invalid asset-ref filter "${ref}". Use the 0.9.0 grammar [bundle//]conceptId, e.g. knowledge/guide.md or lessons/deploy.`, "INVALID_FLAG_VALUE");
     }
 }
-function proposalDurableRef(parsedRef, stashDir) {
+function isRetiredProposalConceptId(conceptId) {
+    const colon = conceptId.indexOf(":");
+    return colon > 0 && stashDirFor(conceptId.slice(0, colon)) !== undefined;
+}
+function proposalMatchesRef(proposalRef, filter) {
+    const proposal = proposalRefIdentity(proposalRef);
+    return (proposal !== undefined &&
+        proposal.conceptId === filter.conceptId &&
+        (filter.bundle === undefined || proposal.bundle === filter.bundle));
+}
+function proposalDurableRef(parsedRef, target) {
     const conceptId = conceptIdFromTypeName(parsedRef.type, parsedRef.name);
     const { origin } = parsedRef;
-    if (origin !== undefined && origin !== "local" && origin !== "stash") {
-        return isBundleSlug(origin) ? `${origin}//${conceptId}` : `${origin}//${parsedRef.type}:${parsedRef.name}`; // WI-8.5b: collapse (non-slug registry origin)
+    if (!isBundleSlug(target.source)) {
+        throw new UsageError(`Proposal target source "${target.source}" is not a valid bundle name.`, "INVALID_FLAG_VALUE");
     }
-    const bundleId = deriveInstallations([{ path: stashDir, writable: true }])[0]?.id ?? slugForPath(stashDir);
-    return `${bundleId}//${conceptId}`;
+    if (origin !== undefined) {
+        if (target.source !== origin) {
+            throw new UsageError(`Proposal ref bundle "${origin}" conflicts with target source "${target.source}".`, "INVALID_FLAG_VALUE");
+        }
+        return `${origin}//${conceptId}`;
+    }
+    return `${target.source}//${conceptId}`;
+}
+function resolveCreateProposalTarget(stashDir, explicit, bundle) {
+    if (explicit) {
+        if (!isBundleSlug(explicit.source) || !explicit.root.trim()) {
+            throw new UsageError("Proposal targets require a current bundle name and materialized root.", "INVALID_FLAG_VALUE");
+        }
+        return { source: explicit.source, root: path.resolve(explicit.root) };
+    }
+    const config = loadConfig();
+    const local = resolveProposalQueueTarget(stashDir, config);
+    if (!bundle || bundle === local.source)
+        return local;
+    if (bundle) {
+        const target = resolveBundleWriteTarget(config, bundle);
+        return { source: target.source.name, root: target.source.path };
+    }
+    return local;
+}
+export function resolveProposalQueueTarget(stashDir, config = loadConfig()) {
+    const root = path.resolve(stashDir);
+    const sources = resolveSourceEntries(root, config);
+    const sourceIndex = sources.findIndex((source) => path.resolve(source.path) === root);
+    const source = sources[sourceIndex];
+    const bundleId = sourceIndex >= 0 ? deriveInstallations(sources)[sourceIndex]?.id : undefined;
+    if (!source || !bundleId) {
+        throw new ConfigError(`No bundle owns proposal queue ${root}.`, "INVALID_CONFIG_FILE");
+    }
+    if (!source.registryId && Object.keys(config.bundles ?? {}).length > 0) {
+        throw new ConfigError(`No configured bundle owns proposal queue ${root}.`, "INVALID_CONFIG_FILE");
+    }
+    if (source.writable !== true) {
+        throw new UsageError(`Proposal bundle "${bundleId}" is not writable.`, "INVALID_FLAG_VALUE");
+    }
+    return { source: bundleId, root };
 }
 // ── Public API ──────────────────────────────────────────────────────────────
 /**
@@ -241,17 +300,12 @@ function proposalDurableRef(parsedRef, stashDir) {
  * 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).");
     }
@@ -280,6 +334,9 @@ export function createProposal(stashDir, input, ctx) {
     if (!input.payload.content.trim()) {
         return rejectProposal("empty_content", `Proposal for "${input.ref}" has empty content.`);
     }
+    if (input.target && parsedRef.origin && input.target.source !== parsedRef.origin) {
+        return rejectProposal("invalid_ref", `Qualified proposal ref bundle "${parsedRef.origin}" conflicts with queue target "${input.target.source}".`);
+    }
     // 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
@@ -291,7 +348,9 @@ export function createProposal(stashDir, input, ctx) {
             return rejectProposal("missing_description", `Proposal for "${input.ref}" (source=consolidate) has empty or missing frontmatter description.`);
         }
     }
-    const normalizedRef = proposalDurableRef(parsedRef, stashDir); // durable proposal.ref (WI-8.5a item_ref flip)
+    const proposalTarget = resolveCreateProposalTarget(stashDir, input.target, parsedRef.origin);
+    const normalizedRef = proposalDurableRef(parsedRef, proposalTarget);
+    const targetRoot = path.resolve(proposalTarget.root);
     // WI-6.2: derive the FileChange[] envelope + mint-time beforeHash. The
     // target is resolved against the proposal's OWN stash (a local snapshot —
     // accept re-resolves the write target from config at apply time), and only
@@ -300,9 +359,9 @@ export function createProposal(stashDir, input, ctx) {
     let targetRelPath;
     let mintBeforeContent;
     try {
-        const typeRoot = path.join(stashDir, stashDirFor(parsedRef.type));
+        const typeRoot = path.join(targetRoot, stashDirFor(parsedRef.type));
         const targetAbs = assetPathForName(parsedRef.type, typeRoot, parsedRef.name);
-        targetRelPath = path.relative(stashDir, targetAbs);
+        targetRelPath = path.relative(targetRoot, targetAbs);
         if (fs.existsSync(targetAbs))
             mintBeforeContent = fs.readFileSync(targetAbs, "utf8");
     }
@@ -310,14 +369,35 @@ export function createProposal(stashDir, input, ctx) {
         // Resolution failure degrades to a best-effort create — never blocks the mint.
         targetRelPath = path.join(stashDirFor(parsedRef.type), parsedRef.name);
     }
+    const proposalContent = targetRelPath.toLowerCase().endsWith(".md")
+        ? ensureAkmMarkdownType(input.payload.content, parsedRef.type)
+        : input.payload.content;
     const mintedChanges = [
         {
             path: targetRelPath,
-            after: input.payload.content,
+            after: proposalContent,
             op: mintBeforeContent !== undefined ? "update" : "create",
         },
     ];
     const mintedBeforeHash = mintBeforeContent !== undefined ? contentHash(mintBeforeContent) : undefined;
+    if (hasCanonicalProposalValidator(parsedRef.type)) {
+        const report = validateProposal({
+            id: "pending",
+            ref: normalizedRef,
+            status: "pending",
+            source: input.source,
+            createdAt: "",
+            updatedAt: "",
+            payload: { ...input.payload, content: proposalContent },
+            changes: mintedChanges,
+            proposedTarget: { source: proposalTarget.source, root: targetRoot },
+        });
+        if (!report.ok) {
+            return rejectProposal("invalid_canonical_structure", `Proposal for "${input.ref}" has invalid ${parsedRef.type} structure:\n${report.findings
+                .map((finding) => `[${finding.kind}] ${finding.message}`)
+                .join("\n")}`);
+        }
+    }
     const fingerprint = computeProposalFingerprint({
         ref: normalizedRef,
         source: input.source,
@@ -350,10 +430,11 @@ export function createProposal(stashDir, input, ctx) {
                 createdAt: created,
                 updatedAt: created,
                 payload: {
-                    content: input.payload.content,
+                    content: proposalContent,
                     ...(input.payload.frontmatter !== undefined ? { frontmatter: input.payload.frontmatter } : {}),
                 },
                 changes: mintedChanges,
+                proposedTarget: { source: proposalTarget.source, root: targetRoot },
                 ...(mintedBeforeHash !== undefined ? { beforeHash: mintedBeforeHash } : {}),
                 ...(sanitizedConfidence !== undefined ? { confidence: sanitizedConfidence } : {}),
                 // Attribution tagging: persist the eligibility lane so it survives to
@@ -461,15 +542,15 @@ export function listProposals(stashDir, options = {}, ctx) {
             return [];
         }
         const status = options.includeArchive ? options.status : "pending";
-        // WI-8.5a: the `ref` filter matches by conceptId (grammar-independent) so a
-        // display/legacy query ref finds the item_ref-spelled row. Applied in JS, not
-        // as a SQL `ref = ?`, since the stored spelling no longer equals the query ref.
-        const wantConceptId = options.ref !== undefined ? filterConceptId(options.ref) : undefined;
+        // Short filters match by conceptId; qualified filters additionally retain
+        // bundle identity. Applied in JS because a short query does not equal the
+        // fully-qualified stored ref.
+        const wantRef = options.ref !== undefined ? filterRefIdentity(options.ref) : undefined;
         return listStateProposals(db, {
             stashDir,
             ...(status !== undefined ? { status } : {}),
         }).filter((p) => {
-            if (options.ref !== undefined && (wantConceptId === undefined || proposalConceptId(p.ref) !== wantConceptId)) {
+            if (wantRef !== undefined && !proposalMatchesRef(p.ref, wantRef)) {
                 return false;
             }
             if (!options.type)
@@ -493,16 +574,35 @@ export function getProposal(stashDir, id, ctx) {
 function requireProposal(db, stashDir, id) {
     const proposal = getStateProposal(db, id, stashDir);
     if (!proposal) {
-        throw new NotFoundError(`Proposal "${id}" not found.`, "FILE_NOT_FOUND");
+        throw new NotFoundError(`Proposal "${id}" not found.`, "PROPOSAL_NOT_FOUND");
     }
     return proposal;
 }
+/**
+ * Lenient counterpart to {@link requireProposal} / {@link getProposal}, used
+ * ONLY on the terminal-status (reject/archive) read paths — `archiveProposal`
+ * and the reject-transaction machinery (`rejectProposalDurably`,
+ * `finalizeRejectTransaction`). Those paths must succeed even when the row's
+ * metadata fails strict decoding (see {@link proposalRowToProposalLenient});
+ * every other reader (accept, revert, show, list's pending branch) keeps
+ * strict decoding via `getProposal`/`requireProposal` unchanged.
+ */
+function requireProposalLenient(db, stashDir, id) {
+    const proposal = getStateProposalLenient(db, id, stashDir);
+    if (!proposal) {
+        throw new NotFoundError(`Proposal "${id}" not found.`, "PROPOSAL_NOT_FOUND");
+    }
+    return proposal;
+}
+function getProposalLenient(stashDir, id, ctx) {
+    return withProposalsDb(stashDir, ctx, (db) => requireProposalLenient(db, stashDir, id));
+}
 /**
  * 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
+ *   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.
@@ -513,21 +613,19 @@ export function resolveProposalId(stashDir, idOrRef, ctx) {
         const exact = getStateProposal(db, idOrRef, stashDir);
         if (exact)
             return exact;
-        // 2. Asset ref in EITHER grammar — most recent pending, else most recent
-        // archived. WI-8.5a: match by conceptId (a UUID carries neither `:` nor `/`,
-        // so both grammars — legacy `skill:x` and new `skills/x` / `bundle//skills/x`
-        // — route here and match the item_ref-spelled stored row).
-        const wantConceptId = idOrRef.includes(":") || idOrRef.includes("/") ? filterConceptId(idOrRef) : undefined;
-        if (wantConceptId !== undefined) {
+        // 2. Asset ref — most recent pending, else most recent archived. Qualified
+        // refs retain bundle identity; short refs match by conceptId in this queue.
+        const wantRef = idOrRef.includes(":") || idOrRef.includes("/") ? filterRefIdentity(idOrRef) : undefined;
+        if (wantRef !== undefined) {
             const byRecency = (proposals) => proposals.sort((a, b) => new Date(b.createdAt ?? 0).getTime() - new Date(a.createdAt ?? 0).getTime())[0];
-            const forConcept = (status) => listStateProposals(db, { stashDir, ...(status !== undefined ? { status } : {}) }).filter((p) => proposalConceptId(p.ref) === wantConceptId);
+            const forConcept = (status) => listStateProposals(db, { stashDir, ...(status !== undefined ? { status } : {}) }).filter((p) => proposalMatchesRef(p.ref, wantRef));
             const pending = byRecency(forConcept("pending"));
             if (pending)
                 return pending;
             const archived = byRecency(forConcept());
             if (archived)
                 return archived;
-            throw new NotFoundError(`No proposal found for ref "${idOrRef}".`, "FILE_NOT_FOUND");
+            throw new NotFoundError(`No proposal found for ref "${idOrRef}".`, "PROPOSAL_NOT_FOUND");
         }
         // 3. UUID prefix (pending queue only).
         const prefixMatches = listStateProposalIdsByPrefix(db, stashDir, idOrRef);
@@ -536,18 +634,37 @@ export function resolveProposalId(stashDir, idOrRef, ctx) {
         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.`, "PROPOSAL_NOT_FOUND");
     });
 }
+/**
+ * Resolve a reject target's id, tolerating a legacy row whose metadata fails
+ * strict decoding. `akm proposal reject` only needs the id — but
+ * {@link resolveProposalId}'s exact-UUID fast path decodes the FULL proposal
+ * just to hand it back, which throws on those rows before the
+ * terminal-status machinery (which reads leniently — see
+ * `requireProposalLenient`) ever runs. Falls back to `resolveProposalId`
+ * unchanged for ref / uuid-prefix inputs, where existing resolution
+ * (including its error semantics) is preserved.
+ */
+export function resolveProposalIdForReject(stashDir, idOrRef, ctx) {
+    const exact = withProposalsDb(stashDir, ctx, (db) => getStateProposalLenient(db, idOrRef, stashDir));
+    if (exact)
+        return exact.id;
+    return resolveProposalId(stashDir, idOrRef, ctx).id;
+}
 /**
  * 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) {
+export function archiveProposal(stashDir, id, status, reason, ctx, gateDecision) {
     return withProposalsDb(stashDir, ctx, (db) => {
         return withImmediateTransaction(db, () => {
-            const existing = requireProposal(db, stashDir, id);
+            // Lenient: archiving (accept OR reject) a legacy row with malformed
+            // changes/proposedTarget metadata must still be able to flip status —
+            // see requireProposalLenient.
+            const existing = requireProposalLenient(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");
             }
@@ -561,18 +678,18 @@ export function archiveProposal(stashDir, id, status, reason, ctx) {
                     ...(reason !== undefined ? { reason } : {}),
                     decidedAt,
                 },
+                ...(gateDecision ? { gateDecision: { ...gateDecision, decidedAt: gateDecision.decidedAt ?? decidedAt } } : {}),
             };
-            upsertProposal(db, updated, stashDir);
+            persistProposalUpdate(db, updated, stashDir);
             return updated;
         });
     });
 }
 /**
  * Record the drain/triage engine's decision onto a proposal (#577).
- * Drain-owned audit machinery — the deterministic drain engine is the only
- * live writer since the 0.9.0 confidence-gate deletion.
+ * Drain-owned audit machinery — the deterministic drain engine is the writer.
  *
- * Stamps `gateDecision` (decision / reason / confidence / thresholds) onto the
+ * Stamps `gateDecision` (decision / reason / measurement / 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`,
@@ -593,7 +710,7 @@ export function recordGateDecision(stashDir, id, decision, ctx) {
                 ...existing,
                 gateDecision: { ...decision, decidedAt: decision.decidedAt ?? nowIso(ctx) },
             };
-            upsertProposal(db, updated, stashDir);
+            persistProposalUpdate(db, updated, stashDir);
             return updated;
         });
     });
@@ -822,7 +939,7 @@ function persistProposalTransactionState(txn, proposal, ctx) {
         const current = requireProposal(db, p.stashDir, p.proposalId);
         if (p.operation === "accept") {
             if (current.status === "accepted") {
-                if (current.acceptedContentHash !== p.publishedHash) {
+                if (current.acceptedTarget?.contentHash !== p.publishedHash) {
                     throw new Error(`Accepted proposal ${p.proposalId} does not match its recovery journal.`);
                 }
                 return current;
@@ -830,18 +947,34 @@ function persistProposalTransactionState(txn, proposal, ctx) {
             if (current.status !== "pending") {
                 throw new Error(`Proposal ${p.proposalId} changed status during acceptance (${current.status}).`);
             }
+            const persistedProposal = proposal.changes.length > 0 && proposal.changes.every((change) => change.path.length > 0)
+                ? withProposalContent(proposal, publishedContent)
+                : {
+                    ...proposal,
+                    payload: { ...proposal.payload, content: publishedContent },
+                    changes: [
+                        {
+                            path: path.relative(txn.journal.root, p.assetPath),
+                            op: p.originalHash === null ? "create" : "update",
+                            after: publishedContent,
+                        },
+                    ],
+                    proposedTarget: { source: p.targetSource, root: txn.journal.root },
+                };
             const accepted = {
-                ...withProposalContent(proposal, publishedContent),
+                ...persistedProposal,
                 status: "accepted",
                 updatedAt: decidedAt,
                 review: { outcome: "accepted", decidedAt },
-                acceptedContentHash: p.publishedHash,
                 acceptedTarget: {
                     source: p.targetSource,
                     root: txn.journal.root,
                     path: p.assetPath,
                     contentHash: p.publishedHash,
                 },
+                ...(p.gateDecision
+                    ? { gateDecision: { ...p.gateDecision, decidedAt: p.gateDecision.decidedAt ?? decidedAt } }
+                    : {}),
                 ...(backupContent !== undefined ? { backupContent } : {}),
             };
             upsertProposal(db, accepted, p.stashDir);
@@ -894,15 +1027,26 @@ async function finalizeProposalTransaction(txn, target, proposal, ctx) {
     if (txn.journal.phase === "asset-published") {
         const commitRoot = target.source.repoPath ?? target.source.path;
         const commitPath = path.relative(commitRoot, p.assetPath).replaceAll(path.sep, "/");
-        commitWriteTargetBoundary(target, `${p.operation === "accept" ? "Update" : "Revert"} ${p.ref}`, {
+        publishWriteTargetTransaction(target, p.gitPublication, {
+            transactionId: txn.journal.transactionId,
+            message: `${p.operation === "accept" ? "Update" : "Revert"} ${p.ref}`,
             paths: [commitPath],
+            snapshots: p.gitSnapshots ?? {},
+            onCommitRecorded: (commit) => {
+                // biome-ignore lint/style/noNonNullAssertion: publishWriteTargetTransaction throws when absent
+                const publication = p.gitPublication;
+                if (publication.commit !== commit) {
+                    publication.commit = commit;
+                    advanceTxn(txn, "asset-published");
+                }
+            },
         });
         persistProposalTransactionState(txn, proposal, ctx);
         advanceTxn(txn, "proposal-persisted");
     }
     let accepted = getProposal(p.stashDir, p.proposalId, ctx);
     if (txn.journal.phase === "proposal-persisted") {
-        if (!(await indexWrittenAssets(txn.journal.root, [p.assetPath]))) {
+        if (!(await indexWrittenAssets(txn.journal.root, [p.assetPath], { bundleId: target.source.name }))) {
             throw new Error(`Proposal ${p.proposalId} index finalization failed.`);
         }
         advanceTxn(txn, "index-finalized");
@@ -919,12 +1063,15 @@ async function finalizeProposalTransaction(txn, target, proposal, ctx) {
 }
 /**
  * Kind-level safety fence for a `proposal` journal, run before any recovery
- * action (mirrors the legacy per-engine fence; the engine fences root binding
- * and the uniform changes[] separately).
+ * action. The engine fences root binding and the uniform changes[] separately.
  */
 function fenceProposalTxnJournal(journal, txnDir, root) {
     const p = journal.payload;
+    const refIdentity = proposalRefIdentity(p.ref);
     if (!["accept", "revert"].includes(p.operation) ||
+        !p.targetSource ||
+        !p.targetKind ||
+        refIdentity?.bundle === undefined ||
         !isWithin(p.assetPath, root) ||
         ![p.contentPath, p.backupPath]
             .filter((candidate) => candidate !== null)
@@ -933,6 +1080,17 @@ function fenceProposalTxnJournal(journal, txnDir, root) {
         throw new Error(`Refusing unsafe proposal transaction journal at ${path.join(txnDir, "journal.json")}.`);
     }
 }
+function resolveProposalRecoveryTarget(config, journal) {
+    let target;
+    try {
+        target = resolveBundleWriteTarget(config, journal.payload.targetSource);
+    }
+    catch {
+        throw new UsageError(`Proposal transaction ${journal.transactionId} target is no longer configured.`, "INVALID_FLAG_VALUE");
+    }
+    const bundleId = canonicalBundleIdForTarget(config, target);
+    return { ...target, source: { ...target.source, name: bundleId } };
+}
 async function recoverProposalTransactions(target, stashDir, ctx) {
     const completed = new Map();
     const nsDir = txnNamespaceDir(target.source.path);
@@ -954,13 +1112,17 @@ async function recoverProposalTransactions(target, stashDir, ctx) {
             continue;
         if (path.resolve(journal.payload.stashDir) !== path.resolve(stashDir))
             continue;
-        if (journal.version !== 1 || canonicalTxnRoot(journal.root) !== canonicalTxnRoot(target.source.path)) {
+        if (journal.version !== 1 ||
+            canonicalTxnRoot(journal.root) !== canonicalTxnRoot(target.source.path) ||
+            journal.payload.targetSource !== target.source.name ||
+            journal.payload.targetKind !== target.source.kind) {
             throw new Error(`Refusing unsafe proposal transaction journal at ${journalPath}.`);
         }
         fenceProposalTxnJournal(journal, transactionDir, target.source.path);
         const txn = { journal, journalPath, dir: transactionDir };
-        if (journal.phase === "prepared")
+        if (journal.phase === "prepared") {
             rollbackPreparedProposalTransaction(txn);
+        }
         else if (journal.phase !== "committed") {
             const proposal = getProposal(stashDir, journal.payload.proposalId, ctx);
             completed.set(journal.payload.proposalId, await finalizeProposalTransaction(txn, target, proposal, ctx));
@@ -984,20 +1146,17 @@ export async function recoverProposalTransactionsForStash(stashDir, config, ctx,
     }
     const recoveredRoots = new Set();
     for (const journal of matches) {
-        let target;
-        try {
-            target = resolveWriteTarget(config, journal.payload.targetSource);
-        }
-        catch {
-            target = resolveWriteTarget(config);
-        }
-        if (canonicalTxnRoot(target.source.path) !== canonicalTxnRoot(journal.root)) {
+        let target = resolveProposalRecoveryTarget(config, journal);
+        const requiresGitPublication = matches.some((candidate) => candidate.phase === "asset-published" && canonicalTxnRoot(candidate.root) === canonicalTxnRoot(journal.root));
+        if (requiresGitPublication)
+            target = prepareWriteTargetForMutation(target, { allowAhead: true });
+        if (canonicalTxnRoot(target.source.path) !== canonicalTxnRoot(journal.root) ||
+            journal.payload.targetKind !== target.source.kind) {
             throw new Error(`Proposal transaction ${journal.transactionId} is bound to a different target root.`);
         }
         const key = path.resolve(target.source.path);
         if (recoveredRoots.has(key))
             continue;
-        await recoverTxnsForRoot(target.source.path, (journal) => journal.kind === "mv");
         const recovered = await recoverProposalTransactions(target, stashDir, ctx);
         for (const [id, proposal] of recovered)
             completed.set(id, proposal);
@@ -1010,13 +1169,12 @@ const REJECT_TXN_PHASES = ["prepared", "state-persisted", "event-finalized", "co
 function finalizeRejectTransaction(txn, ctx) {
     const p = txn.journal.payload;
     const decidedAt = txn.journal.decidedAt;
-    let proposal = getProposal(p.stashDir, p.proposalId, ctx);
+    // Lenient: a reject transaction must run to completion even on a legacy
+    // row whose metadata fails strict decoding — see requireProposalLenient.
+    let proposal = getProposalLenient(p.stashDir, p.proposalId, ctx);
     if (txn.journal.phase === "prepared") {
         if (proposal.status === "pending") {
-            proposal = archiveProposal(p.stashDir, p.proposalId, "rejected", p.reason, {
-                ...ctx,
-                now: () => Date.parse(decidedAt),
-            });
+            proposal = archiveProposal(p.stashDir, p.proposalId, "rejected", p.reason, { ...ctx, now: () => Date.parse(decidedAt) }, p.gateDecision);
         }
         else if (proposal.status !== "rejected") {
             throw new Error(`Proposal ${p.proposalId} changed status during rejection (${proposal.status}).`);
@@ -1025,7 +1183,7 @@ function finalizeRejectTransaction(txn, ctx) {
         txnMutationHook("reject-state-persisted");
     }
     if (txn.journal.phase === "state-persisted") {
-        proposal = getProposal(p.stashDir, p.proposalId, ctx);
+        proposal = getProposalLenient(p.stashDir, p.proposalId, ctx);
         const eventRef = proposal.ref;
         const eventMeta = {
             proposalId: proposal.id,
@@ -1075,11 +1233,13 @@ function recoverRejectTransaction(stashDir, proposalId, ctx) {
     }
     return undefined;
 }
-export function rejectProposalDurably(stashDir, proposalId, reason, ctx) {
+export function rejectProposalDurably(stashDir, proposalId, reason, ctx, gateDecision) {
     const recovered = recoverRejectTransaction(stashDir, proposalId, ctx);
     if (recovered)
         return recovered;
-    const proposal = getProposal(stashDir, proposalId, ctx);
+    // Lenient: see requireProposalLenient — the reject decision itself must not
+    // be blocked by a legacy row's malformed changes/proposedTarget metadata.
+    const proposal = getProposalLenient(stashDir, proposalId, ctx);
     if (proposal.status !== "pending") {
         throw new UsageError(`Proposal ${proposalId} is not pending (current status: ${proposal.status}). Only pending proposals can be rejected.`, "INVALID_FLAG_VALUE");
     }
@@ -1087,7 +1247,12 @@ export function rejectProposalDurably(stashDir, proposalId, reason, ctx) {
         kind: REJECT_TXN_KIND,
         root: stashDir,
         changes: [],
-        payload: { proposalId, stashDir, ...(reason !== undefined ? { reason } : {}) },
+        payload: {
+            proposalId,
+            stashDir,
+            ...(reason !== undefined ? { reason } : {}),
+            ...(gateDecision ? { gateDecision } : {}),
+        },
         decidedAt: nowIso(ctx),
     });
     const rejected = finalizeRejectTransaction(txn, ctx);
@@ -1095,6 +1260,8 @@ export function rejectProposalDurably(stashDir, proposalId, reason, ctx) {
     return rejected;
 }
 function prepareProposalTransaction(stashDir, target, proposal, ref, content, options, ctx) {
+    if (options.operation === "accept")
+        assertAkmAssetWrite(target.source);
     const assetPath = resolveAssetFilePathSafe(target.source, ref);
     if (!assetPath)
         throw new Error(`Cannot resolve proposal target ${proposal.ref}.`);
@@ -1105,6 +1272,7 @@ function prepareProposalTransaction(stashDir, target, proposal, ref, content, op
     // and the initial `prepared` journal must be written exactly ONCE with its
     // final contents (crash runners intercept the first rename per phase).
     const transactionId = mintTxnId();
+    const gitPublication = captureGitPublication(target);
     const transactionDir = txnDirFor(target.source.path, transactionId);
     fs.mkdirSync(transactionDir, { recursive: true, mode: 0o700 });
     const contentPath = path.join(transactionDir, "published-content");
@@ -1136,6 +1304,7 @@ function prepareProposalTransaction(stashDir, target, proposal, ref, content, op
             proposalId: proposal.id,
             stashDir,
             targetSource: target.source.name,
+            targetKind: target.source.kind,
             assetPath,
             ref: proposal.ref,
             contentPath,
@@ -1144,7 +1313,9 @@ function prepareProposalTransaction(stashDir, target, proposal, ref, content, op
             backupPath: persistedBackupPath,
             originalHash: options.originalHash,
             publishedHash,
+            ...(gitPublication ? { gitPublication } : {}),
             ...(options.eventMetadata ? { eventMetadata: options.eventMetadata } : {}),
+            ...(options.gateDecision ? { gateDecision: options.gateDecision } : {}),
         },
         decidedAt: nowIso(ctx),
     });
@@ -1161,7 +1332,7 @@ function prepareProposalTransaction(stashDir, target, proposal, ref, content, op
     }
     return txn;
 }
-function publishProposalAsset(txn) {
+function publishProposalAsset(txn, target) {
     const p = txn.journal.payload;
     try {
         if (p.originalHash !== null) {
@@ -1173,6 +1344,9 @@ function publishProposalAsset(txn) {
         }
         fs.linkSync(p.publishPath, p.assetPath);
         fsyncTxnDir(path.dirname(p.assetPath));
+        const snapshot = captureWriteTargetPathSnapshot(target, p.assetPath);
+        if (snapshot)
+            p.gitSnapshots = { [snapshot.path]: snapshot.state };
         advanceTxn(txn, "asset-published");
     }
     catch (error) {
@@ -1181,6 +1355,175 @@ function publishProposalAsset(txn) {
         throw error;
     }
 }
+function resolveRecordedProposalTarget(config, proposalId, binding, explicitTarget) {
+    let target;
+    try {
+        target = explicitTarget
+            ? resolveWriteTarget(config, explicitTarget)
+            : resolveBundleWriteTarget(config, binding.source);
+    }
+    catch {
+        throw new UsageError(`Proposal ${proposalId} is bound to target "${binding.source}" at ${binding.root}, but that writable target is no longer configured.`, "INVALID_FLAG_VALUE");
+    }
+    const targetBundleId = canonicalBundleIdForTarget(config, target);
+    if (targetBundleId !== binding.source || path.resolve(target.source.path) !== path.resolve(binding.root)) {
+        throw new UsageError(`Proposal ${proposalId} is bound to target "${binding.source}" at ${binding.root}; ` +
+            `--target "${explicitTarget}" resolves to "${targetBundleId}" at ${target.source.path}.`, "INVALID_FLAG_VALUE");
+    }
+    return { ...target, source: { ...target.source, name: targetBundleId } };
+}
+function resolveProposalWriteTarget(config, proposal, explicitTarget, queueTarget) {
+    if (!proposal.proposedTarget) {
+        const identity = proposalRefIdentity(proposal.ref);
+        if (!identity)
+            throw new UsageError(`Proposal ${proposal.id} has an invalid ref.`, "INVALID_PROPOSAL");
+        if (identity.bundle !== undefined) {
+            const target = resolveBundleWriteTarget(config, identity.bundle);
+            const targetBundleId = canonicalBundleIdForTarget(config, target);
+            if (explicitTarget !== undefined) {
+                const explicit = resolveWriteTarget(config, explicitTarget);
+                if (canonicalBundleIdForTarget(config, explicit) !== identity.bundle) {
+                    throw new UsageError(`Proposal ${proposal.id} ref is bound to bundle "${identity.bundle}", which conflicts with --target "${explicitTarget}".`, "INVALID_FLAG_VALUE");
+                }
+            }
+            if (queueTarget && canonicalBundleIdForTarget(config, queueTarget) !== identity.bundle) {
+                throw new UsageError(`Proposal ${proposal.id} is bound to a different queue target.`, "INVALID_FLAG_VALUE");
+            }
+            return { ...target, source: { ...target.source, name: targetBundleId } };
+        }
+        const target = explicitTarget ? resolveWriteTarget(config, explicitTarget) : queueTarget;
+        if (!target) {
+            throw new UsageError(`Unbound short proposal ${proposal.id} requires an explicit --target or authenticated --queue context.`, "INVALID_PROPOSAL");
+        }
+        const targetBundleId = canonicalBundleIdForTarget(config, target);
+        return { ...target, source: { ...target.source, name: targetBundleId } };
+    }
+    if (queueTarget && explicitTarget === undefined) {
+        const queueBundleId = canonicalBundleIdForTarget(config, queueTarget);
+        if (queueBundleId !== proposal.proposedTarget.source ||
+            path.resolve(queueTarget.source.path) !== path.resolve(proposal.proposedTarget.root)) {
+            throw new UsageError(`Proposal ${proposal.id} is bound to a different queue target.`, "INVALID_FLAG_VALUE");
+        }
+    }
+    return resolveRecordedProposalTarget(config, proposal.id, proposal.proposedTarget, explicitTarget);
+}
+// ── D2 (#730) — OKF v0.2 provenance stamping on promotion ───────────────────
+//
+// The proposals system already tracks exactly what OKF v0.2 wants on disk —
+// `source`/`sourceRun` (PROV-DM modeled, `proposal-types.ts` §80-120),
+// `gateDecision` (`:200-237`), `review` (`:170-174`) — but none of it leaves
+// state.db. This section projects it onto the written asset's frontmatter at
+// promotion time, AKM-native assets only (an OKF-adapter target never reaches
+// this function — `assertAkmAssetWrite` rejects it earlier in
+// `promoteProposalWithLease`, before any of this runs).
+//
+// Two DISTINCT actors, deliberately not conflated (documented judgment call —
+// see the PR body for the alternative considered and rejected):
+//   - `generated.by` answers "what produced the CONTENT" — keyed on
+//     `isAutomatedProposalSource(proposal.source)`: an automated pipeline
+//     (reflect/distill/consolidate/extract/improve/schema-repair) stamps
+//     `akm/<pkgVersion>`; a human-initiated source (propose/remember/import)
+//     or the semi-automated `feedback` source stamps `human:<actorId>`.
+//   - `verified[0].by` answers "what accepted/reviewed THIS promotion" —
+//     keyed on whether a `gateDecision` was supplied to THIS call: present
+//     (the automated drain/triage path decided) stamps `akm/<pkgVersion>`;
+//     absent (a human explicitly ran `akm proposal accept`) stamps
+//     `human:<actorId>`. Every promotion reaches this function via exactly
+//     one of those two paths, so `verified` is always stamped — there is no
+//     third, unreviewed path to disk.
+/** Resolve the `human:<id>` actor id — the OS account, the least-surprising stand-in for "the human at this keyboard" in a system with no multi-user identity. */
+function resolveActorId(ctx) {
+    if (ctx?.actorId)
+        return ctx.actorId();
+    try {
+        const username = os.userInfo().username?.trim();
+        return username ? username : "local";
+    }
+    catch {
+        return "local";
+    }
+}
+/** `generated.by` — keyed on the SOURCE that produced the content (see file-header note above). */
+function generatedByActor(proposal, ctx) {
+    return isAutomatedProposalSource(proposal.source) ? `akm/${pkgVersion}` : `human:${resolveActorId(ctx)}`;
+}
+/** `verified[0].by` — keyed on whether THIS promotion was gated (automated) or a direct human accept (see file-header note above). */
+function verifiedByActor(gateDecision, ctx) {
+    return gateDecision !== undefined ? `akm/${pkgVersion}` : `human:${resolveActorId(ctx)}`;
+}
+/** True for a plain (non-null, non-array) object. */
+function isPlainRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Stamp OKF v0.2 provenance onto ONE promoted asset's frontmatter (D2.1/D2.2/
+ * D2.3), in the **hybrid** on-disk shape settled by the #730 review:
+ *
+ * - `generated: {by, at}` and `verified: [{by, at}]` are written **bare at the
+ *   top level**, exactly as OKF v0.2 spells them (SPEC §5.2/§5.3). Neither key
+ *   has any pre-existing AKM consumer, so spelling them the spec's way costs
+ *   nothing and makes `okf-support.md`'s "AKM Markdown is an OKF-compatible
+ *   superset" positioning actually true for trust metadata: a third-party OKF
+ *   v0.2 reader pointed at an AKM stash sees conformant provenance.
+ * - `sources` stays namespaced under `provenance:`, because a bare top-level
+ *   `sources:` genuinely collides with the pre-existing AKM-native wiki
+ *   citation-**string** convention
+ *   (`indexer/passes/metadata.ts#applyWikiFrontmatter`, which silently drops
+ *   non-strings) on a promoted wiki page.
+ *
+ * The read side back into `IndexDocument.provenance` is
+ * `metadata.ts#applyProvenanceFrontmatter` (which accepts both this shape and
+ * the older fully-nested one), carried through `akm-adapter.ts`'s
+ * `DOCUMENT_JSON_CARRIED_FIELDS` (D2.4).
+ *
+ * A no-op frontmatter mutation preserves the existing frontmatter block's raw
+ * body bytes (mirrors `frontmatter.ts#mutateFrontmatter`'s documented
+ * contract) rather than reshaping via `assembleAsset`, which would strip
+ * leading body blank lines / force a trailing newline. A file with no
+ * frontmatter block at all (non-conformant input) gains one via
+ * `assembleAsset`, exactly as any other first-frontmatter write would.
+ */
+function stampProposalProvenance(content, proposal, gateDecision, ctx, nowIsoStr) {
+    const parsed = parseFrontmatter(content);
+    const fm = { ...parsed.data };
+    const existingProvenance = isPlainRecord(fm.provenance) ? fm.provenance : {};
+    // Bare `generated:` — OKF v0.2's replacement for `timestamp` (SPEC §13).
+    fm.generated = { by: generatedByActor(proposal, ctx), at: nowIsoStr };
+    // Bare `verified:` — append, so independent confirmations accumulate rather
+    // than the newest overwriting the record. Both the bare list and the older
+    // nested spelling are absorbed, so a re-promotion never loses history.
+    const priorVerified = Array.isArray(fm.verified)
+        ? fm.verified
+        : Array.isArray(existingProvenance.verified)
+            ? existingProvenance.verified
+            : [];
+    fm.verified = [
+        ...priorVerified,
+        { by: verifiedByActor(gateDecision, ctx), at: gateDecision?.decidedAt ?? nowIsoStr },
+    ];
+    // `sources` alone stays namespaced — bare `sources:` is the wiki
+    // citation-string convention. Drop the nested provenance block entirely when
+    // it would otherwise be empty, so unrelated assets gain no dead key.
+    const provenance = { ...existingProvenance };
+    delete provenance.generatedBy;
+    delete provenance.generatedAt;
+    delete provenance.verified;
+    const evidenceSources = fm.evidenceSources;
+    if (Array.isArray(evidenceSources)) {
+        const sources = evidenceSources
+            .filter((s) => typeof s === "string" && s.trim().length > 0)
+            .map((resource) => ({ resource: resource.trim() }));
+        if (sources.length > 0)
+            provenance.sources = sources;
+    }
+    if (Object.keys(provenance).length > 0)
+        fm.provenance = provenance;
+    else
+        delete fm.provenance;
+    return parsed.frontmatter !== null
+        ? `---\n${serializeFrontmatter(fm)}\n---\n${parsed.content}`
+        : assembleAsset(fm, parsed.content);
+}
 /**
  * Validate a proposal, then promote it through the canonical
  * {@link writeAssetToSource} dispatch (the single place that branches on
@@ -1196,47 +1539,171 @@ function publishProposalAsset(txn) {
 export async function promoteProposal(stashDir, config, id, options = {}, ctx) {
     return withAssetMutationLease("proposal-accept", () => promoteProposalWithLease(stashDir, config, id, options, ctx));
 }
+function promotionLintBlockers(raw, assetPath, targetRoot, refType, config) {
+    let data;
+    let body;
+    let frontmatter;
+    if (refType === "task") {
+        try {
+            const parsed = parseYaml(raw);
+            data = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+        }
+        catch {
+            data = {};
+        }
+        body = raw;
+        frontmatter = null;
+    }
+    else {
+        ({ data, content: body, frontmatter } = parseFrontmatter(raw));
+    }
+    const resolvedRoot = path.resolve(targetRoot);
+    const extraStashRoots = resolveSourceEntries(targetRoot, config)
+        .map((source) => source.path)
+        .filter((sourcePath) => path.resolve(sourcePath) !== resolvedRoot);
+    return runBaseChecks({
+        filePath: assetPath,
+        relPath: path.relative(targetRoot, assetPath),
+        raw,
+        data,
+        body,
+        frontmatter,
+        fix: false,
+        stashRoot: targetRoot,
+        extraStashRoots,
+    }).filter((finding) => PROMOTION_LINT_BLOCKERS.has(finding.issue));
+}
+/** Build and validate the exact stamped bytes promotion would publish, without writing. */
+export function preflightProposalPromotion(config, proposal, options = {}, ctx) {
+    const repairedContent = repairProposalContent(proposalContent(proposal));
+    const preparedProposal = repairedContent === proposalContent(proposal) ? proposal : withProposalContent(proposal, repairedContent);
+    const report = validateProposal(preparedProposal);
+    if (!report.ok) {
+        const message = report.findings.map((finding) => `[${finding.kind}] ${finding.message}`).join("\n");
+        throw new UsageError(`Proposal ${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.");
+    }
+    const ref = parseRefInput(preparedProposal.ref);
+    if (!stashDirFor(ref.type)) {
+        throw new UsageError(`Proposal ${proposal.id} targets unknown asset type "${ref.type}".`, "INVALID_FLAG_VALUE");
+    }
+    const target = resolveProposalWriteTarget(config, preparedProposal, options.target, options.queueTarget);
+    const assetPath = resolveAssetFilePathSafe(target.source, ref);
+    if (!assetPath)
+        throw new UsageError(`Cannot resolve proposal target ${preparedProposal.ref}.`, "INVALID_PROPOSAL");
+    assertAkmAssetWrite(target.source);
+    const stampedContent = assetPath.toLowerCase().endsWith(".md")
+        ? stampProposalProvenance(repairedContent, preparedProposal, options.gateDecision, ctx, nowIso(ctx))
+        : repairedContent;
+    const lintBlockers = promotionLintBlockers(stampedContent, assetPath, target.source.path, ref.type, config);
+    if (lintBlockers.length > 0) {
+        const message = lintBlockers.map((finding) => `[${finding.issue}] ${finding.detail}`).join("\n");
+        throw new UsageError(`Proposal ${proposal.id} failed lint:\n${message}`, "INVALID_PROPOSAL", "Fix or explicitly suppress the reported lint findings, then retry.");
+    }
+    return { proposal: preparedProposal, repairedContent, ref, target, assetPath, stampedContent };
+}
+/**
+ * The change-transaction pre-commit gate — the `BundleAdapter.validate()`
+ * interface contract's OTHER stated consumer (`core/adapter/bundle-adapter.ts`
+ * doc comment, alongside `lint --fix`). Runs the target's OWN adapter's
+ * `validate()` over the ONE pending write `preflight` describes, with a
+ * {@link createValidateContext} overlay carrying the proposal's about-to-be-
+ * written bytes — so the adapter sees the bundle AS IT WOULD LOOK the instant
+ * after this transaction commits, without ever touching disk.
+ *
+ * DELIBERATELY ADVISORY, not blocking (see the report for the full
+ * rationale): the akm adapter's `missing-ref` check resolves prose refs
+ * through the SAME core overlay `resolveRef` that closes the OKF/llm-wiki
+ * lint gaps — and that resolver is proven to disagree with the legacy
+ * `commands/lint/base-linter.ts#checkMissingRefs` resolver in one specific,
+ * real case: a fully-qualified `bundle//conceptId` prose ref (or a bare
+ * frontmatter xref) whose leading segment does NOT name a registered AKM
+ * placement type. The legacy resolver treats an unrecognized type prefix as
+ * "not a locally-checkable ref, skip it, never flag missing" (whole-hearted
+ * leniency for cross-bundle / foreign-format refs); this module's core
+ * resolver additionally tries the ref as a literal on-disk path — the
+ * resolution non-akm adapters (OKF, llm-wiki) actually NEED for their own
+ * same-component conceptIds — which means it CAN report `missing-ref` for a
+ * foreign-typed prose ref the legacy checker always let through. Promoting a
+ * proposal is a live, user-facing write path; blocking it on a diagnostic
+ * that can disagree with the existing (already-tested, already-run)
+ * `promotionLintBlockers` gate a few lines above is not a change to make
+ * without a dedicated equivalence pass first. So: this computes and surfaces
+ * the finding (visible via `warn`, and never thrown) without changing whether
+ * ANY promotion succeeds or fails — proving the wiring end-to-end on real
+ * proposal data while leaving today's blocking behavior completely
+ * untouched. Never throws: a validate() failure here must not corrupt or
+ * half-apply the transaction that follows.
+ */
+async function runAdapterPreCommitCheck(config, preflight) {
+    try {
+        const adapterId = preflight.target.source.adapterId ?? "akm";
+        const adapter = adapterForId(adapterId);
+        if (!adapter)
+            return;
+        const root = preflight.target.source.path;
+        const relPath = path.relative(root, preflight.assetPath).replace(/\\/g, "/");
+        if (!relPath || relPath.startsWith(".."))
+            return; // resolved outside its own bundle root — nothing to check
+        const change = {
+            path: relPath,
+            after: preflight.stampedContent,
+            op: fs.existsSync(preflight.assetPath) ? "update" : "create",
+        };
+        const extraRoots = resolveSourceEntries(root, config)
+            .map((source) => source.path)
+            .filter((sourcePath) => path.resolve(sourcePath) !== path.resolve(root));
+        const componentCtx = createValidateContext({ root, extraRoots, changes: [change] });
+        const diagnostics = await adapter.validate({ id: preflight.target.selector ?? adapterId, adapter: adapterId, root, writable: true }, [change], componentCtx);
+        if (diagnostics.length > 0) {
+            const summary = diagnostics.map((d) => `[${d.issue}] ${d.detail}`).join("; ");
+            warn(`[proposal] pre-commit adapter check for ${preflight.proposal.id} found (non-blocking): ${summary}`);
+        }
+    }
+    catch (error) {
+        // Advisory only — never let a validate() failure interrupt or corrupt the
+        // promotion transaction that follows.
+        warn(`[proposal] pre-commit adapter check for ${preflight.proposal.id} threw (ignored, non-blocking): ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 async function promoteProposalWithLease(stashDir, config, id, options, ctx) {
+    recoverRejectTransaction(stashDir, id, ctx);
     let proposal = getProposal(stashDir, id, ctx);
-    // 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(proposalContent(proposal));
-    const proposalToValidate = repairedContent !== proposalContent(proposal) ? withProposalContent(proposal, repairedContent) : proposal;
+    const proposalToValidate = repairedContent === proposalContent(proposal) ? proposal : withProposalContent(proposal, repairedContent);
     const report = validateProposal(proposalToValidate);
     if (!report.ok) {
-        const message = report.findings.map((f) => `[${f.kind}] ${f.message}`).join("\n");
+        const message = report.findings.map((finding) => `[${finding.kind}] ${finding.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.");
     }
+    const ref = parseRefInput(proposalToValidate.ref);
+    if (!stashDirFor(ref.type)) {
+        throw new UsageError(`Proposal ${id} targets unknown asset type "${ref.type}".`, "INVALID_FLAG_VALUE");
+    }
     // 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 !== proposalContent(proposal)) {
         withProposalsDb(stashDir, ctx, (db) => {
-            upsertProposal(db, withProposalContent(proposal, repairedContent), stashDir);
+            persistProposalUpdate(db, proposalToValidate, stashDir);
         });
     }
-    const ref = parseRefInput(proposalToValidate.ref);
-    if (!stashDirFor(ref.type)) {
-        throw new UsageError(`Proposal ${id} targets unknown asset type "${ref.type}".`, "INVALID_FLAG_VALUE");
-    }
     await recoverProposalTransactionsForStash(stashDir, config, ctx, id);
     proposal = getProposal(stashDir, id, ctx);
-    const target = resolveWriteTarget(config, options.target);
-    await recoverTxnsForRoot(target.source.path, (journal) => journal.kind === "mv");
-    if (proposal.status === "accepted" && proposal.acceptedContentHash) {
+    const target = resolveProposalWriteTarget(config, proposal, options.target, options.queueTarget);
+    if (proposal.status === "accepted") {
+        if (!proposal.acceptedTarget) {
+            throw new UsageError(`Accepted proposal ${id} has no recorded target.`, "INVALID_PROPOSAL");
+        }
         const assetPath = resolveAssetFilePathSafe(target.source, ref);
-        if (proposal.acceptedTarget &&
-            (proposal.acceptedTarget.source !== target.source.name ||
-                path.resolve(proposal.acceptedTarget.root) !== path.resolve(target.source.path) ||
-                !assetPath ||
-                path.resolve(proposal.acceptedTarget.path) !== path.resolve(assetPath))) {
+        if (proposal.acceptedTarget.source !== target.source.name ||
+            path.resolve(proposal.acceptedTarget.root) !== path.resolve(target.source.path) ||
+            !assetPath ||
+            path.resolve(proposal.acceptedTarget.path) !== path.resolve(assetPath)) {
             throw new UsageError(`proposal ${id} is bound to a different accepted target`, "INVALID_FLAG_VALUE");
         }
-        if (!assetPath || !fs.existsSync(assetPath) || proposalFileHash(assetPath) !== proposal.acceptedContentHash) {
+        if (!assetPath ||
+            !fs.existsSync(assetPath) ||
+            proposalFileHash(assetPath) !== proposal.acceptedTarget.contentHash) {
             throw new UsageError(`Accepted proposal ${id} does not match the current asset content.`, "INVALID_FLAG_VALUE");
         }
         return { proposal, assetPath, ref: proposal.ref };
@@ -1244,9 +1711,13 @@ async function promoteProposalWithLease(stashDir, config, id, options, 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");
     }
-    const assetPath = resolveAssetFilePathSafe(target.source, ref);
+    const preflight = preflightProposalPromotion(config, proposal, { ...options, queueTarget: target }, ctx);
+    await runAdapterPreCommitCheck(config, preflight);
+    const mutationTarget = prepareWriteTargetForMutation(target);
+    const assetPath = resolveAssetFilePathSafe(mutationTarget.source, ref);
     if (!assetPath)
         throw new UsageError(`Cannot resolve proposal target ${proposal.ref}.`, "INVALID_PROPOSAL");
+    assertWriteTargetPathsClean(mutationTarget.source, [assetPath]);
     let backup;
     if (fs.existsSync(assetPath)) {
         try {
@@ -1256,16 +1727,48 @@ async function promoteProposalWithLease(stashDir, config, id, options, ctx) {
             throw new Error(`Proposal backup read failed for ${assetPath}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    const transaction = prepareProposalTransaction(stashDir, target, proposalToValidate, ref, repairedContent, {
+    if (proposal.beforeHash !== undefined && (!backup || proposalHash(backup) !== proposal.beforeHash)) {
+        throw new UsageError(`Proposal target changed after proposal ${id} was created; refusing to overwrite newer content.`, "INVALID_FLAG_VALUE");
+    }
+    if (proposal.beforeHash === undefined &&
+        backup !== undefined &&
+        proposal.changes.some((change) => change.op === "create")) {
+        throw new UsageError(`Proposal target was created after proposal ${id}; refusing to overwrite newer content.`, "INVALID_FLAG_VALUE");
+    }
+    assertAkmAssetWrite(mutationTarget.source);
+    // D2 (#730): stamp OKF v0.2 provenance onto the promoted content BEFORE
+    // lint/write — reaching this point already proves the target is AKM-native
+    // (assertAkmAssetWrite above rejects an OKF-adapter target first), so the
+    // OKF write-rejection contract (runbook §10) is untouched: this code never
+    // runs for it. Markdown-only: a task/env/script/other non-markdown target
+    // has no frontmatter block to stamp into.
+    //
+    // workflow-format-unification removed the re-validation fallback that used
+    // to live here: every AKM-native markdown type (workflow included) now
+    // validates its frontmatter against a schema whose closed key set is
+    // `envelope ∪ type-keys` (`schemas/akm-workflow.json` $ref's
+    // `schemas/akm-asset-envelope.json`, which already admits `generated`/
+    // `verified`/`provenance`/`status`/`stale_after`). A validator rejecting the
+    // machine-stamped keys it is contractually required to admit is structurally
+    // impossible now, so falling back to unstamped content on rejection would
+    // only silently hide a real regression instead of promoting stamped content.
+    const stampedContent = preflight.stampedContent;
+    const proposalForPreflight = preflight.proposal;
+    const refIdentity = proposalRefIdentity(proposalForPreflight.ref);
+    const proposalForMutation = refIdentity?.bundle === undefined
+        ? { ...proposalForPreflight, ref: `${target.source.name}//${refIdentity?.conceptId ?? ""}` }
+        : proposalForPreflight;
+    const transaction = prepareProposalTransaction(stashDir, mutationTarget, proposalForMutation, ref, stampedContent, {
         operation: "accept",
         originalHash: backup ? proposalHash(backup) : null,
         backup,
         eventMetadata: options.eventMetadata,
+        gateDecision: options.gateDecision,
     }, ctx);
-    publishProposalAsset(transaction);
-    const accepted = await finalizeProposalTransaction(transaction, target, proposalToValidate, ctx);
+    publishProposalAsset(transaction, mutationTarget);
+    const accepted = await finalizeProposalTransaction(transaction, mutationTarget, proposalForMutation, ctx);
     cleanupTxn(transaction.dir);
-    return { proposal: accepted, assetPath: transaction.journal.payload.assetPath, ref: proposal.ref };
+    return { proposal: accepted, assetPath: transaction.journal.payload.assetPath, ref: accepted.ref };
 }
 /**
  * Restore the prior content of an accepted proposal from the backup captured
@@ -1299,19 +1802,15 @@ async function revertProposalWithLease(stashDir, config, id, options, ctx) {
     await recoverProposalTransactionsForStash(stashDir, config, ctx, id);
     proposal = getProposal(stashDir, id, ctx);
     if (proposal.status === "reverted") {
-        if (options.target)
-            resolveWriteTarget(config, options.target);
-        const target = proposal.legacyAcceptedTargetDerived
-            ? resolveWritableTargets(config).find((candidate) => candidate.source.name === proposal.acceptedTarget?.source &&
-                path.resolve(candidate.source.path) === path.resolve(proposal.acceptedTarget?.root ?? ""))
-            : resolveWriteTarget(config, options.target);
-        const requestedAssetPath = target ? resolveAssetFilePathSafe(target.source, ref) : undefined;
-        if (!target ||
-            !requestedAssetPath ||
-            (proposal.acceptedTarget &&
-                (proposal.acceptedTarget.source !== target.source.name ||
-                    path.resolve(proposal.acceptedTarget.root) !== path.resolve(target.source.path) ||
-                    path.resolve(proposal.acceptedTarget.path) !== path.resolve(requestedAssetPath)))) {
+        if (!proposal.acceptedTarget) {
+            throw new UsageError(`Reverted proposal ${id} has no recorded target.`, "INVALID_PROPOSAL");
+        }
+        const target = resolveRecordedProposalTarget(config, id, proposal.acceptedTarget, options.target);
+        const requestedAssetPath = resolveAssetFilePathSafe(target.source, ref);
+        if (!requestedAssetPath ||
+            proposal.acceptedTarget.source !== target.source.name ||
+            path.resolve(proposal.acceptedTarget.root) !== path.resolve(target.source.path) ||
+            path.resolve(proposal.acceptedTarget.path) !== path.resolve(requestedAssetPath)) {
             throw new UsageError(`proposal ${id} is bound to a different accepted target`, "INVALID_FLAG_VALUE");
         }
         return {
@@ -1327,96 +1826,26 @@ async function revertProposalWithLease(stashDir, config, id, options, ctx) {
     if (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 proposalBody = proposalContent(proposal);
-    const legacyAccepted = proposalBody.endsWith("\n") ? proposalBody : `${proposalBody}\n`;
-    let acceptedHash = proposal.acceptedTarget?.contentHash ?? proposal.acceptedContentHash ?? proposalHash(legacyAccepted);
-    const writableTargets = resolveWritableTargets(config);
-    let target;
-    let assetPath;
     if (!proposal.acceptedTarget) {
-        if (options.target)
-            resolveWriteTarget(config, options.target);
-        const candidates = writableTargets.flatMap((candidate) => {
-            const candidatePath = resolveAssetFilePathSafe(candidate.source, ref);
-            return candidatePath ? [{ target: candidate, assetPath: candidatePath }] : [];
-        });
-        const matching = candidates.filter((candidate) => fs.existsSync(candidate.assetPath) && proposalFileHash(candidate.assetPath) === acceptedHash);
-        if (matching.length > 1) {
-            throw new UsageError(`legacy proposal ${id} has ambiguous accepted content in multiple writable targets; refusing revert`, "INVALID_FLAG_VALUE");
-        }
-        const existing = candidates.filter((candidate) => fs.existsSync(candidate.assetPath));
-        if (matching.length === 0 && existing.length > 0) {
-            throw new UsageError(`asset content changed after proposal ${id} was accepted; refusing to clobber the newer content`, "INVALID_FLAG_VALUE");
-        }
-        if (matching.length === 0 && candidates.length !== 1) {
-            throw new UsageError(`legacy proposal ${id} has no accepted asset and ${candidates.length} writable targets can own the ref; ownership is ambiguous`, "INVALID_FLAG_VALUE");
-        }
-        const owner = matching[0] ?? candidates[0];
-        if (!owner) {
-            throw new UsageError(`legacy proposal ${id} has no writable target that can own ${proposal.ref}`, "INVALID_FLAG_VALUE");
-        }
-        const acceptedAssetWasAbsent = matching.length === 0;
-        proposal = withProposalsDb(stashDir, ctx, (db) => withImmediateTransaction(db, () => {
-            const current = requireProposal(db, stashDir, id);
-            if (current.status !== "accepted" || current.acceptedTarget) {
-                throw new Error(`Proposal ${id} changed while deriving its legacy revert target.`);
-            }
-            const bound = {
-                ...current,
-                acceptedContentHash: acceptedHash,
-                acceptedTarget: {
-                    source: owner.target.source.name,
-                    root: owner.target.source.path,
-                    path: owner.assetPath,
-                    contentHash: acceptedHash,
-                },
-                legacyAcceptedTargetDerived: true,
-                ...(acceptedAssetWasAbsent ? { legacyAcceptedAssetWasAbsent: true } : {}),
-            };
-            upsertProposal(db, bound, stashDir);
-            return bound;
-        }));
-        txnMutationHook("legacy-target-derived");
-        target = owner.target;
-        assetPath = owner.assetPath;
-    }
-    else if (proposal.legacyAcceptedTargetDerived) {
-        const acceptedTarget = proposal.acceptedTarget;
-        if (!acceptedTarget)
-            throw new Error(`Legacy proposal ${id} lost its derived accepted target.`);
-        const bound = writableTargets.find((candidate) => {
-            const candidatePath = resolveAssetFilePathSafe(candidate.source, ref);
-            return (candidate.source.name === acceptedTarget.source &&
-                path.resolve(candidate.source.path) === path.resolve(acceptedTarget.root) &&
-                candidatePath !== undefined &&
-                path.resolve(candidatePath) === path.resolve(acceptedTarget.path));
-        });
-        if (!bound) {
-            throw new UsageError(`legacy proposal ${id} is bound to a writable target that is no longer configured`, "INVALID_FLAG_VALUE");
-        }
-        target = bound;
-        assetPath = acceptedTarget.path;
-    }
-    else {
-        target = resolveWriteTarget(config, options.target);
-        const requestedAssetPath = resolveAssetFilePathSafe(target.source, ref);
-        if (proposal.acceptedTarget.source !== target.source.name ||
-            path.resolve(proposal.acceptedTarget.root) !== path.resolve(target.source.path) ||
-            !requestedAssetPath ||
-            path.resolve(proposal.acceptedTarget.path) !== path.resolve(requestedAssetPath)) {
-            throw new UsageError(`proposal ${id} is bound to a different accepted target`, "INVALID_FLAG_VALUE");
-        }
-        assetPath = requestedAssetPath;
-    }
-    await recoverTxnsForRoot(target.source.path, (journal) => journal.kind === "mv");
-    acceptedHash = proposal.acceptedTarget?.contentHash ?? proposal.acceptedContentHash ?? acceptedHash;
-    const acceptedAssetExists = fs.existsSync(assetPath);
-    if ((fs.existsSync(assetPath) && proposalFileHash(assetPath) !== acceptedHash) ||
-        (!fs.existsSync(assetPath) && !proposal.legacyAcceptedAssetWasAbsent)) {
+        throw new UsageError(`Accepted proposal ${id} has no recorded target.`, "INVALID_PROPOSAL");
+    }
+    let target = resolveRecordedProposalTarget(config, id, proposal.acceptedTarget, options.target);
+    const requestedAssetPath = resolveAssetFilePathSafe(target.source, ref);
+    if (proposal.acceptedTarget.source !== target.source.name ||
+        path.resolve(proposal.acceptedTarget.root) !== path.resolve(target.source.path) ||
+        !requestedAssetPath ||
+        path.resolve(proposal.acceptedTarget.path) !== path.resolve(requestedAssetPath)) {
+        throw new UsageError(`proposal ${id} is bound to a different accepted target`, "INVALID_FLAG_VALUE");
+    }
+    const assetPath = requestedAssetPath;
+    const acceptedHash = proposal.acceptedTarget.contentHash;
+    target = prepareWriteTargetForMutation(target);
+    if (!fs.existsSync(assetPath) || proposalFileHash(assetPath) !== acceptedHash) {
         throw new UsageError(`asset content changed after proposal ${id} was accepted; refusing to clobber the newer content`, "INVALID_FLAG_VALUE");
     }
-    const transaction = prepareProposalTransaction(stashDir, target, proposal, ref, backupContent, { operation: "revert", originalHash: acceptedAssetExists ? acceptedHash : null }, ctx);
-    publishProposalAsset(transaction);
+    assertWriteTargetPathsClean(target.source, [assetPath]);
+    const transaction = prepareProposalTransaction(stashDir, target, proposal, ref, backupContent, { operation: "revert", originalHash: acceptedHash }, ctx);
+    publishProposalAsset(transaction, target);
     const reverted = await finalizeProposalTransaction(transaction, target, proposal, ctx);
     cleanupTxn(transaction.dir);
     return { proposal: reverted, assetPath, ref: proposal.ref };
@@ -1432,17 +1861,13 @@ export function diffProposal(stashDir, config, id, options = {}, ctx) {
     const ref = parseRefInput(proposal.ref);
     let targetPath;
     let existing = null;
-    try {
-        const target = resolveWriteTarget(config, options.target);
+    const readTarget = (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.
-    }
+    };
+    readTarget(resolveProposalWriteTarget(config, proposal, options.target, options.queueTarget));
     const proposed = proposalContent(proposal);
     if (existing === null) {
         return {
@@ -1488,14 +1913,12 @@ registerTxnKind(PROPOSAL_TXN_KIND, {
     finalize: async (txn) => {
         const p = txn.journal.payload;
         const config = loadConfig();
-        let target;
-        try {
-            target = resolveWriteTarget(config, p.targetSource);
-        }
-        catch {
-            target = resolveWriteTarget(config);
+        let target = resolveProposalRecoveryTarget(config, txn.journal);
+        if (txn.journal.phase === "asset-published") {
+            target = prepareWriteTargetForMutation(target, { allowAhead: true });
         }
-        if (canonicalTxnRoot(target.source.path) !== canonicalTxnRoot(txn.journal.root)) {
+        if (canonicalTxnRoot(target.source.path) !== canonicalTxnRoot(txn.journal.root) ||
+            p.targetKind !== target.source.kind) {
             throw new Error(`Proposal transaction ${txn.journal.transactionId} is bound to a different target root.`);
         }
         const proposal = getProposal(p.stashDir, p.proposalId);