akm-cli 0.9.18 → 0.9.19-alpha.1

package/dist/commands/proposal/repository.js

@@ -21,7 +21,7 @@ import { assembleAsset, serializeFrontmatter } from "../../core/asset/asset-seri
 import { carryForwardBookkeepingFrontmatter, parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
-import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
+import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { proposalContent } from "../../core/file-change.js";
 import { canonicalBundleIdForTarget, resolveBundleWriteTarget } from "../../core/mutation-target.js";
@@ -34,7 +34,7 @@ import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { deriveInstallations } from "../../indexer/installations.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertEventOnce } from "../../storage/repositories/events-repository.js";
-import { recordImproveLedger, recordImproveLedgerDecision, } from "../../storage/repositories/improve-ledger-repository.js";
+import { CONSOLIDATE_LEDGER_SOURCE, forgetImproveLedgerDecision, recordImproveLedger, recordImproveLedgerDecision, reopenImproveLedgerDecision, } from "../../storage/repositories/improve-ledger-repository.js";
 import { getStateProposal, listStateProposalIdsByPrefix, listStateProposals, upsertProposal, } from "../../storage/repositories/proposals-repository.js";
 import { openSqliteReadSnapshot } from "../../storage/sqlite-read-snapshot.js";
 import { pkgVersion } from "../../version.js";
@@ -42,8 +42,8 @@ import { contentHash } from "../improve/content-hash.js";
 import { writeSupersededEdge } from "../improve/memory/memory-belief.js";
 import { archiveCleanupCandidate, derivedTwinPath } from "../improve/memory/memory-improve.js";
 import { runBaseChecks } from "../lint/base-linter.js";
-import { formatNewAssetDiff, formatUnifiedDiff } from "./diff-format.js";
-import { ASSET_MISSING_GATE_REASON, EXPIRED_GATE_REASON, isAutomatedProposalSource, isRetireProposal, isValidProposalSource, PROPOSAL_SOURCES, STALE_TARGET_GATE_REASON, } from "./proposal-types.js";
+import { formatNewAssetDiff, formatRetireDiff, formatUnifiedDiff } from "./diff-format.js";
+import { ASSET_MISSING_GATE_REASON, EXPIRED_GATE_REASON, isAutomatedProposalSource, isRetireProposal, isValidProposalSource, PROPOSAL_SOURCES, proposalWaitingSince, STALE_TARGET_GATE_REASON, } from "./proposal-types.js";
 import { canonicalOnlyProposalValidators, hasCanonicalProposalValidator, runProposalValidators, } from "./validators/proposal-validators.js";
 import { repairProposalContent, validateProposal } from "./validators/proposals.js";
 export { AUTOMATED_PROPOSAL_SOURCES, isAutomatedProposalSource, isValidProposalSource, PROPOSAL_SOURCES, } from "./proposal-types.js";
@@ -141,6 +141,28 @@ export function resolveProposalQueueTarget(stashDir, config = loadConfig()) {
     }
     return { source: bundleId, root };
 }
+/**
+ * The configured bundle that owns the asset `itemRef` names when it is not the
+ * bundle rooted at `target`; otherwise `undefined`. A differing name is
+ * confirmed by the owner's root, so one bundle known by two spellings is never
+ * taken for two, and an owner that cannot be resolved is never refused on.
+ */
+function otherOwningBundle(itemRef, target) {
+    try {
+        const owner = parseBundleRef(itemRef).bundle;
+        if (owner === undefined || owner === target.source)
+            return undefined;
+        const sources = resolveSourceEntries(target.root, loadConfig());
+        const ownerSource = sources[deriveInstallations(sources).findIndex((installation) => installation.id === owner)];
+        return ownerSource !== undefined && path.resolve(ownerSource.path) !== path.resolve(target.root)
+            ? owner
+            : undefined;
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        return undefined;
+    }
+}
 /**
  * Create a pending proposal (a random UUID id). Obviously invalid input is
  * refused with a typed `proposal_creation_rejected` event. The mint and its
@@ -190,9 +212,13 @@ export function createProposal(stashDir, input, ctx) {
             return rejectProposal("missing_description", `Proposal for "${input.ref}" (source=consolidate) has empty or missing frontmatter description.`);
         }
     }
+    const proposalTarget = resolveCreateProposalTarget(stashDir, input.target, parsedRef.origin);
+    const owner = input.itemRef ? otherOwningBundle(input.itemRef, proposalTarget) : undefined;
+    if (owner) {
+        return rejectProposal("cross_bundle", `Proposal for "${input.ref}" rewrites ${input.itemRef}, which bundle "${owner}" owns, but its queue target is bundle "${proposalTarget.source}". Filing it there would fork the asset out of "${owner}" or overwrite this bundle's copy with content taken from the other. Improve it in its own bundle instead (\`akm improve --bundle ${owner}\`).`);
+    }
     // The FileChange envelope, and the target's before-hashes as of mint (the
     // freshness check at accept compares against them).
-    const proposalTarget = resolveCreateProposalTarget(stashDir, input.target, parsedRef.origin);
     const normalizedRef = proposalDurableRef(parsedRef, proposalTarget);
     const targetRoot = path.resolve(proposalTarget.root);
     let targetRelPath;
@@ -454,6 +480,25 @@ function ledgerOutcomeForDecision(status, gateDecision) {
     }
     return "rejected";
 }
+/**
+ * What a decision's ledger row is about. A promotion's row is keyed by its
+ * source memory, so a decision on it names that memory, together with the body
+ * hash the promotion was queued against — this is what holds the memory back
+ * until it changes (`isContentDrivenDecision`). Any other proposal, and a
+ * promotion minted before the hash was recorded, is keyed by its own ref.
+ * Every decision that can create a row when none carries the proposal id — a
+ * reject, an accept and a drain deferral alike — must key it this way: a stray
+ * row under the knowledge ref carries the proposal id, so a later verdict
+ * updates that one and never reaches the memory's own row.
+ */
+function decisionLedgerSubject(proposal) {
+    if (proposal.source === CONSOLIDATE_LEDGER_SOURCE &&
+        proposal.promotionSource !== undefined &&
+        proposal.promotionSourceHash !== undefined) {
+        return { ref: proposal.promotionSource, contentHash: proposal.promotionSourceHash };
+    }
+    return { ref: proposal.ref };
+}
 /** Archive a pending proposal as accepted/rejected, recording the decision in the ledger in the same transaction. */
 export function archiveProposal(stashDir, id, status, reason, ctx, gateDecision) {
     return withProposalsDb(ctx, (db) => withImmediateTransaction(db, () => {
@@ -473,7 +518,7 @@ export function archiveProposal(stashDir, id, status, reason, ctx, gateDecision)
         recordImproveLedgerDecision(db, {
             proposalId: updated.id,
             stashDir,
-            ref: updated.ref,
+            ...decisionLedgerSubject(updated),
             source: updated.source,
             outcome: ledgerOutcomeForDecision(status, gateDecision),
             at: decidedAt,
@@ -500,7 +545,7 @@ export function recordGateDecision(stashDir, id, decision, ctx) {
             recordImproveLedgerDecision(db, {
                 proposalId: updated.id,
                 stashDir,
-                ref: updated.ref,
+                ...decisionLedgerSubject(updated),
                 source: updated.source,
                 outcome: "review_needed",
                 at: decidedAt,
@@ -551,9 +596,10 @@ export function purgeOrphanProposals(stashDir, sourceDirs, ctx) {
 }
 /**
  * Archive pending proposals older than `archiveRetentionDays` (default 90;
- * 0 disables) as rejected with an `expired` gate decision and a
- * `proposal_expired` event. The ledger records `expired` — a short grace, not
- * the rejection window, since nobody judged the content.
+ * 0 disables; counted from the last reopen, if any) as rejected with an
+ * `expired` gate decision and a `proposal_expired` event. The ledger records
+ * `expired` — a short grace, not the rejection window, since nobody judged the
+ * content.
  */
 export function expireStaleProposals(stashDir, config, ctx) {
     const t0 = Date.now();
@@ -572,7 +618,9 @@ export function expireStaleProposals(stashDir, config, ctx) {
         // way back short of the pair pass finding it again from scratch.
         if (isRetireProposal(p))
             continue;
-        const createdMs = new Date(p.createdAt).getTime();
+        // A reopened proposal's wait starts over at the reopen (#997): expiring it
+        // on its original age would undo the reopen at the next sweep.
+        const createdMs = new Date(proposalWaitingSince(p)).getTime();
         if (!Number.isFinite(createdMs) || nowMs - createdMs < retentionDays * MS_PER_DAY)
             continue;
         try {
@@ -690,7 +738,7 @@ function persistProposalDecision(stashDir, proposal, decision, ctx) {
         recordImproveLedgerDecision(db, {
             proposalId: next.id,
             stashDir,
-            ref: next.ref,
+            ...decisionLedgerSubject(next),
             source: next.source,
             outcome: ledgerOutcomeForDecision(accept ? "accepted" : "reverted"),
             at: decision.decidedAt,
@@ -1591,17 +1639,197 @@ async function revertProposalWithLease(stashDir, config, id, options, ctx) {
     await indexWrittenProposalAsset(target, assetPath);
     return { proposal: reverted, assetPath, ref: proposal.ref };
 }
+/** The message of the stale-target refusal `check` raises, else `undefined`. */
+function staleRefusal(check) {
+    try {
+        check();
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            return error.message;
+        throw error;
+    }
+}
+/**
+ * Why `proposal` cannot be reopened, or `undefined` when it can. Only a
+ * rejected proposal comes back, and only one accept would not refuse as stale:
+ * a retire proposal needs its successor and both recorded body hashes to still
+ * match (B2), any other its target to be what it was minted against
+ * (STALE, R20) — so a reopened proposal is never one the next accept refuses.
+ */
+function reopenRefusal(config, proposal, queueTarget) {
+    if (proposal.status !== "rejected") {
+        return `it is not rejected (current status: ${proposal.status}); only a rejected proposal can be reopened.`;
+    }
+    if (proposal.changes.length === 0 || proposal.proposedTarget === undefined) {
+        // A pending row must carry both (proposalToRowValues), which a row from
+        // before the change envelope existed cannot.
+        return "it was recorded before proposals carried their change envelope, so it cannot go back in the queue.";
+    }
+    const target = resolveProposalWriteTarget(config, proposal, undefined, queueTarget);
+    const assetPath = resolveAssetFilePathSafe(target.source, parseRefInput(proposal.ref));
+    if (!assetPath)
+        return "its target cannot be resolved.";
+    if (!isRetireProposal(proposal)) {
+        return staleRefusal(() => void readFreshProposalTarget(proposal, assetPath, proposalContent(proposal)));
+    }
+    if (!proposal.retirement)
+        return "it has no retirement metadata.";
+    if (!fs.existsSync(assetPath)) {
+        return "its retired file no longer exists (already retired, or removed by something else).";
+    }
+    const { retirement } = proposal;
+    return staleRefusal(() => assertRetirementStillFresh(proposal.id, proposal.ref, retirement, target.source, fs.readFileSync(assetPath)));
+}
+/** The assets a retire proposal speaks for — the one it retires and its successor — as bundle-less concept ids, the way the pair pass keys them. */
+function retireHeldRefs(proposal) {
+    return [proposal.ref, proposal.retirement?.successorRef].flatMap((ref) => {
+        const conceptId = ref === undefined ? undefined : proposalRefIdentity(ref)?.conceptId;
+        return conceptId === undefined ? [] : [conceptId];
+    });
+}
+const REOPEN_REFUSED_HINT = "Only a rejected proposal whose target is unchanged can be reopened; `akm proposal list --status rejected` lists the candidates.";
+const REOPEN_RETIRE_CONFLICT_HINT = "Only one pending retire proposal can involve a document: accept or reject the pending one (or reopen just one of a clashing pair), then reopen the other.";
+/**
+ * The pair pass never has two pending retire proposals speak for one asset
+ * (`pendingRetireRefs`): accepting one would strand the other. Reopening must
+ * not break that either — a rejected pair can meanwhile have been re-paired
+ * with something else. `held` maps each asset to the pending retire proposal
+ * that has it; a proposal that clears this claims its assets, so two in one
+ * batch that clash refuse the later.
+ */
+function retireConflict(proposal, held) {
+    if (!isRetireProposal(proposal))
+        return undefined;
+    const refs = retireHeldRefs(proposal);
+    for (const ref of refs) {
+        const holder = held.get(ref);
+        if (holder !== undefined) {
+            return `${ref} is already part of retire proposal ${holder}, which is pending or being reopened with this one; only one pending retire proposal may involve an asset.`;
+        }
+    }
+    for (const ref of refs)
+        held.set(ref, proposal.id);
+    return undefined;
+}
+/**
+ * Put rejected proposals back in the queue (`akm proposal reopen`, #997): a
+ * rejection is otherwise final, and it also suppresses the pair pass from ever
+ * re-proposing a retirement (its record keys the pair), so a mistaken one
+ * could not be undone. Each proposal returns to `pending` with the rejection —
+ * and the gate verdict that came with it — kept in `reviewHistory` (the verdict
+ * itself is cleared, unless it is a `deferred` hand-off to a person), its
+ * ledger row reset (the pair pass keys off proposal status, so the pair is no
+ * longer suppressed and, while pending, cannot be minted twice), and a
+ * `proposal_reopened` event recorded, all in one transaction.
+ *
+ * All-or-nothing: every id is checked (see {@link reopenRefusal} and
+ * {@link retireConflict}) before any is reopened, and one refusal leaves the
+ * whole batch untouched.
+ */
+export function reopenProposals(stashDir, config, ids, options = {}, ctx) {
+    return withProposalsDb(ctx, (db) => withImmediateTransaction(db, () => {
+        const proposals = [...new Set(ids)].map((id) => requireProposal(db, stashDir, id));
+        const held = new Map();
+        for (const pending of listStateProposals(db, { stashDir, status: "pending" })) {
+            if (isRetireProposal(pending))
+                for (const ref of retireHeldRefs(pending))
+                    held.set(ref, pending.id);
+        }
+        const refusals = proposals.flatMap((proposal) => {
+            const refusal = reopenRefusal(config, proposal, options.queueTarget);
+            const conflict = refusal === undefined ? retireConflict(proposal, held) : undefined;
+            const reason = refusal ?? conflict;
+            return reason === undefined
+                ? []
+                : [{ proposal: `${proposal.id} (${proposal.ref})`, reason, isConflict: conflict !== undefined }];
+        });
+        if (refusals.length > 0) {
+            // A retire conflict is not about the target changing, so it gets its own hint.
+            const hints = [
+                ...(refusals.some((refusal) => !refusal.isConflict) ? [REOPEN_REFUSED_HINT] : []),
+                ...(refusals.some((refusal) => refusal.isConflict) ? [REOPEN_RETIRE_CONFLICT_HINT] : []),
+            ];
+            throw new UsageError(proposals.length === 1
+                ? `Proposal ${refusals[0]?.proposal} cannot be reopened: ${refusals[0]?.reason}`
+                : `Cannot reopen ${refusals.length} of ${proposals.length} proposals; none were reopened:\n${refusals
+                    .map((refusal) => `  - ${refusal.proposal}: ${refusal.reason}`)
+                    .join("\n")}`, "INVALID_FLAG_VALUE", hints.join(" "));
+        }
+        const decidedAt = nowIso(ctx);
+        return proposals.map((existing) => {
+            const reopened = {
+                ...existing,
+                status: "pending",
+                updatedAt: decidedAt,
+                review: undefined,
+                // A reopened proposal is adjudicated afresh: a `staged` verdict would
+                // let the drain accept it unseen, and another gate's `auto-rejected`
+                // would have the drain skip it. A `deferred` one is the quality
+                // gate's hand-off to a person, which the drain must keep honouring
+                // (drainProposals leaves it alone), so it stays.
+                gateDecision: existing.gateDecision?.outcome === "deferred" ? existing.gateDecision : undefined,
+                reviewHistory: [
+                    ...(existing.reviewHistory ?? []),
+                    {
+                        ...(existing.review !== undefined ? { review: existing.review } : {}),
+                        ...(existing.gateDecision !== undefined ? { gateDecision: existing.gateDecision } : {}),
+                        reopenedAt: decidedAt,
+                        ...(options.reason !== undefined ? { reopenReason: options.reason } : {}),
+                    },
+                ],
+            };
+            upsertProposal(db, reopened, stashDir);
+            if (isRetireProposal(existing)) {
+                // A retire mint writes no ledger row, so the one its rejection wrote goes.
+                forgetImproveLedgerDecision(db, stashDir, existing.id);
+            }
+            else {
+                reopenImproveLedgerDecision(db, {
+                    proposalId: existing.id,
+                    stashDir,
+                    source: existing.source,
+                    at: decidedAt,
+                    detail: options.reason !== undefined ? `reopened: ${options.reason}` : "reopened",
+                });
+            }
+            insertEventOnce(db, {
+                eventType: "proposal_reopened",
+                ts: decidedAt,
+                ref: reopened.ref,
+                metadata: {
+                    proposalId: reopened.id,
+                    source: reopened.source,
+                    ...(reopened.sourceRun !== undefined ? { sourceRun: reopened.sourceRun } : {}),
+                    ...(options.reason !== undefined ? { reason: options.reason } : {}),
+                },
+                idempotencyKey: `${reopened.id}:reopened:${decidedAt}`,
+            });
+            return reopened;
+        });
+    }));
+}
 /** The proposal against the asset its accept would overwrite (same target resolution as accept). */
 export function diffProposal(stashDir, config, id, options = {}, ctx) {
     const proposal = getProposal(stashDir, id, ctx);
     const target = resolveProposalWriteTarget(config, proposal, options.target, options.queueTarget);
     const targetPath = resolveAssetFilePathSafe(target.source, parseRefInput(proposal.ref));
     const existing = targetPath && fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : null;
-    // A retire proposal's primary change deletes its target rather than
-    // writing content: "proposed" is empty and the diff shows the whole body
-    // being removed, reusing the ordinary unified-diff formatter instead of
-    // proposalContent() (which has nothing to read for a delete).
-    const proposed = isRetireProposal(proposal) ? "" : proposalContent(proposal);
+    if (isRetireProposal(proposal)) {
+        // A retire proposal's primary change deletes its target rather than
+        // writing content (proposalContent() has nothing to read for a delete):
+        // accept archives the file, it never replaces it with a blank one, so the
+        // diff shows the file leaving — not a "proposed" side (#997).
+        return {
+            existing,
+            proposed: "",
+            unified: formatRetireDiff(proposal.ref, existing, proposal.retirement?.successorRef),
+            isNew: false,
+            ...(targetPath ? { targetPath } : {}),
+        };
+    }
+    const proposed = proposalContent(proposal);
     return {
         existing,
         proposed,

package/dist/commands/read/knowledge.js

@@ -168,11 +168,11 @@ function parseWriteRefs(rawRefs, flag) {
     }
     return parsedRefs;
 }
-function resolveWriteRefRoots(target) {
+function resolveWriteRefRoots(target, targetFlag) {
     const cfg = loadConfig();
     let writeTarget;
     try {
-        writeTarget = resolveWriteTarget(cfg, target);
+        writeTarget = resolveWriteTarget(cfg, target, { flag: targetFlag });
     }
     catch (error) {
         if (!target)
@@ -297,11 +297,11 @@ export const XREF_SOFT_CAP = 5;
  * {@link XREF_SOFT_CAP} refs emits a stderr warning (soft cap) but still
  * returns them all.
  */
-export function resolveXrefsForWrite(rawXrefs, target) {
+export function resolveXrefsForWrite(rawXrefs, target, targetFlag) {
     const parsedRefs = parseWriteRefs(rawXrefs, "--xref");
     if (parsedRefs.length === 0)
         return [];
-    const { roots } = resolveWriteRefRoots(target);
+    const { roots } = resolveWriteRefRoots(target, targetFlag);
     const unresolved = [];
     const xrefs = [];
     for (const parsed of parsedRefs) {
@@ -386,13 +386,13 @@ function isParseableYamlMapping(frontmatter) {
     }
 }
 /** Resolve any qualified supersedes ref as the mutation target for remember/import. */
-export function resolveSupersedesWriteTarget(rawRefs, target) {
+export function resolveSupersedesWriteTarget(rawRefs, target, targetFlag) {
     const config = loadConfig();
     let effectiveTarget = target;
     for (const parsed of parseWriteRefs(rawRefs, "--supersedes")) {
         if (!parsed.origin)
             continue;
-        const resolved = resolveMutationTarget(config, { type: parsed.type, name: parsed.name, origin: parsed.origin }, effectiveTarget).target;
+        const resolved = resolveMutationTarget(config, { type: parsed.type, name: parsed.name, origin: parsed.origin }, effectiveTarget, { flag: targetFlag }).target;
         effectiveTarget = resolved.selector ?? resolved.source.name;
     }
     return effectiveTarget;
@@ -428,17 +428,17 @@ const SUPERSEDE_REJECTED_TYPES = new Set(["secret", "env", "task", "script"]);
  * constraint (and never dirtying a non-target source outside its boundary
  * commit). A ref that resolves only in another configured source — read-only
  * OR writable-but-not-the-target — is returned with `writable: false` and a
- * reason (naming the `--target` remedy when the source is writable); the
+ * reason (naming the target-flag remedy when the source is writable); the
  * caller writes the correction anyway and reports the demotion as not
  * applied.
  *
  * Returns the deduplicated plan in argv order; empty input returns [].
  */
-export function resolveSupersedesForWrite(rawRefs, target) {
+export function resolveSupersedesForWrite(rawRefs, target, targetFlag) {
     const parsedRefs = parseWriteRefs(rawRefs, "--supersedes");
     if (parsedRefs.length === 0)
         return [];
-    const { roots } = resolveWriteRefRoots(target);
+    const { roots } = resolveWriteRefRoots(target, targetFlag);
     const plan = [];
     const unresolved = [];
     for (const parsed of parsedRefs) {
@@ -491,7 +491,7 @@ export function resolveSupersedesForWrite(rawRefs, target) {
                 : {
                     reason: namedWritableSource
                         ? `resolves outside the write target and the working stash, in writable source "${namedWritableSource}" at ${root}; ` +
-                            `re-run with --target ${namedWritableSource} to demote it there`
+                            `re-run with ${targetFlag ?? "--target"} ${namedWritableSource} to demote it there`
                         : `resolves outside the write target and the working stash, in a read-only source at ${root}; ` +
                             "demotion only applies to assets in the write target or the working stash",
                 }),
@@ -518,7 +518,9 @@ export async function writeMarkdownAsset(options) {
     const subPath = normalizeCreateSubPath(options.path);
     const baseName = normalizeMarkdownAssetName(options.name, inferAssetName(options.content, options.fallbackPrefix, options.preferredName));
     const normalizedName = combineCreatePath(subPath, baseName);
-    const resolved = resolveMutationTarget(cfg, { type: options.type, name: normalizedName }, options.target);
+    const resolved = resolveMutationTarget(cfg, { type: options.type, name: normalizedName }, options.target, {
+        flag: options.targetFlag,
+    });
     const { target } = resolved;
     const { source, config } = target;
     const typeRoot = path.join(source.path, options.type === "knowledge" ? "knowledge" : "memories");

package/dist/commands/read/remember-cli.js

@@ -33,6 +33,8 @@ async function fetchSimilarMemories(query, excludeRef, eventSource) {
         return [];
     }
 }
+/** The flag `remember` takes for its destination, as its errors spell it. */
+const TARGET_FLAG = "--bundle";
 /**
  * `--target` was renamed to `--bundle` on `remember` in 0.9 (S8). citty is
  * non-strict, so the retired spelling is silently absorbed rather than
@@ -153,8 +155,8 @@ export const rememberCommand = defineJsonCommand({
         // untouched. Refs resolvable only in a configured extra stash source are
         // accepted (cross-stash provenance).
         const rawSupersedes = parseAllFlagValues("--supersedes");
-        const writeTarget = resolveSupersedesWriteTarget(rawSupersedes, args.bundle);
-        const xrefs = resolveXrefsForWrite(parseAllFlagValues("--xref"), writeTarget);
+        const writeTarget = resolveSupersedesWriteTarget(rawSupersedes, args.bundle, TARGET_FLAG);
+        const xrefs = resolveXrefsForWrite(parseAllFlagValues("--xref"), writeTarget, TARGET_FLAG);
         // Collect and validate --supersedes occurrences (repeatable). Same
         // before-any-write validation contract: an unresolvable ref exits 2 with
         // nothing written AND nothing demoted (no partial correction). The
@@ -162,7 +164,7 @@ export const rememberCommand = defineJsonCommand({
         // (correction provenance per the back-linking conventions); the demotion
         // itself runs inside writeMarkdownAsset, ordered before the git boundary
         // commit.
-        const supersedes = resolveSupersedesForWrite(rawSupersedes, writeTarget);
+        const supersedes = resolveSupersedesForWrite(rawSupersedes, writeTarget, TARGET_FLAG);
         for (const s of supersedes) {
             if (!xrefs.includes(s.ref))
                 xrefs.push(s.ref);
@@ -206,6 +208,7 @@ export const rememberCommand = defineJsonCommand({
                 preferredName: inferAssetName(body, "memory"),
                 force: args.force,
                 target: writeTarget,
+                targetFlag: TARGET_FLAG,
                 path: args.path,
                 supersedes,
             });
@@ -313,6 +316,7 @@ export const rememberCommand = defineJsonCommand({
             preferredName: inferAssetName(body, "memory"),
             force: args.force,
             target: writeTarget,
+            targetFlag: TARGET_FLAG,
             path: args.path,
             supersedes,
         });

package/dist/commands/sources/source-clone.js

@@ -39,7 +39,7 @@ export async function akmClone(options) {
     // are not bundle slugs).
     const parsed = parseQualifiedRefInput(options.sourceRef);
     const config = hasUnmanagedDest ? undefined : loadConfig();
-    const resolvedWriteTarget = config ? resolveWriteTarget(config, options.target) : undefined;
+    const resolvedWriteTarget = config ? resolveWriteTarget(config, options.target, { flag: "--bundle" }) : undefined;
     const writeTarget = resolvedWriteTarget ? prepareWriteTargetForMutation(resolvedWriteTarget) : undefined;
     // An unmanaged --dest does not require any configured write target.
     let allSources;

package/dist/commands/tasks/tasks-cli.js

@@ -212,7 +212,7 @@ const tasksAddCommand = defineJsonCommand({
         },
         command: {
             type: "string",
-            description: 'Exact shell string to run on the schedule (no AI agent), e.g. "akm improve --strategy frequent".',
+            description: 'Exact shell string to run on the schedule (no AI agent), e.g. "akm improve --strategy reflect-distill".',
         },
         engine: { type: "string", description: "Engine to use for prompt targets (default: defaults.engine)" },
         model: { type: "string", description: "Model override for prompt targets" },

package/dist/commands/tasks/tasks.js

@@ -688,7 +688,7 @@ function taskAssetRef(id) {
 /** The bundle `task add` writes into: its write target, config, stash path, and name. */
 function resolveTaskBundle(target) {
     const config = loadConfig();
-    const resolved = prepareWriteTargetForMutation(resolveWriteTarget(config, target, { requireWritable: true }));
+    const resolved = prepareWriteTargetForMutation(resolveWriteTarget(config, target, { requireWritable: true, flag: "--bundle" }));
     return { resolved, config, stashDir: resolved.source.path, bundleName: resolved.source.name };
 }
 function taskProjectionAssetResolver(config, bundleName, bundleRoot) {
@@ -696,7 +696,8 @@ function taskProjectionAssetResolver(config, bundleName, bundleRoot) {
         if (bundle === bundleName) {
             return { file: await resolveAssetPath(bundleRoot, type, name), bundleRoot };
         }
-        const target = resolveWriteTarget(config, bundle, { requireWritable: false });
+        // `bundle` is the qualifier of an asset ref in the task, not a flag.
+        const target = resolveWriteTarget(config, bundle, { requireWritable: false, flag: "The asset ref's bundle" });
         return {
             file: await resolveAssetPath(target.source.path, type, name),
             bundleRoot: target.source.path,
@@ -723,7 +724,13 @@ export function resolveTaskReadBundle(refBundle, flagBundle) {
     else {
         const configured = resolveActiveConfiguredSources(config).some((source) => source.name === selector);
         const implicit = configured ? undefined : resolveImplicitScheduledBundleTarget(config, selector);
-        resolved = implicit ?? resolveWriteTarget(config, selector, { requireWritable: false });
+        resolved =
+            implicit ??
+                resolveWriteTarget(config, selector, {
+                    requireWritable: false,
+                    // The selector is `--bundle` when given, else the task ref's own bundle qualifier.
+                    flag: flagBundle !== undefined ? "--bundle" : "The task ref's bundle",
+                });
     }
     if (refBundle && resolved.source.name !== refBundle) {
         throw new UsageError(`Task ref bundle ${JSON.stringify(refBundle)} does not match the resolved source.`, "INVALID_FLAG_VALUE");

package/dist/core/mutation-target.js

@@ -50,9 +50,14 @@ function resolveExplicitMutationTarget(config, explicitTarget, options) {
         }
     }
 }
-/** Reconcile a qualified mutation ref with `--target`, then resolve the write destination. */
+/**
+ * Reconcile a qualified mutation ref with the explicit target (`--target`, or
+ * the `options.flag` the caller's command spells), then resolve the write
+ * destination.
+ */
 export function resolveMutationTarget(config, ref, explicitTarget, options = {}) {
-    const writeOptions = { requireWritable: options.requireWritable };
+    const flag = options.flag ?? "--target";
+    const writeOptions = { requireWritable: options.requireWritable, flag };
     const qualifiedTarget = ref.origin ? resolveBundleWriteTarget(config, ref.origin, writeOptions) : undefined;
     const explicitResolved = explicitTarget
         ? resolveExplicitMutationTarget(config, explicitTarget, writeOptions)
@@ -60,7 +65,7 @@ export function resolveMutationTarget(config, ref, explicitTarget, options = {})
     if (qualifiedTarget &&
         explicitResolved &&
         path.resolve(qualifiedTarget.source.path) !== path.resolve(explicitResolved.source.path)) {
-        throw new UsageError(`Qualified ref bundle "${ref.origin}" conflicts with --target "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop --target or select the same bundle.`);
+        throw new UsageError(`Qualified ref bundle "${ref.origin}" conflicts with ${flag} "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop ${flag} or select the same bundle.`);
     }
     let target = qualifiedTarget ?? explicitResolved ?? resolveWriteTarget(config, undefined, writeOptions);
     const bundleId = ref.origin ?? canonicalBundleIdForTarget(config, target);

package/dist/core/write-source.js

@@ -59,16 +59,17 @@ export function resolveWriteTarget(akmConfig, explicitTarget, options = {}) {
     const allConfiguredSources = resolveConfiguredSources(akmConfig);
     const configuredSources = resolveActiveConfiguredSources(akmConfig);
     const requireWritable = options.requireWritable !== false;
+    const flag = options.flag ?? "--target";
     if (explicitTarget) {
         const match = configuredSources.find((s) => s.name === explicitTarget);
         if (!match) {
             if (allConfiguredSources.some((source) => source.name === explicitTarget)) {
                 throw new UsageError(`Bundle "${explicitTarget}" is disabled.`, "INVALID_FLAG_VALUE");
             }
-            throw new UsageError(`--target must reference a source name from your config. No source named "${explicitTarget}" is configured. Run \`akm bundle list\` to see available sources.`, "INVALID_FLAG_VALUE");
+            throw new UsageError(`${flag} must reference a source name from your config. No source named "${explicitTarget}" is configured. Run \`akm bundle list\` to see available sources.`, "INVALID_FLAG_VALUE");
         }
         if (requireWritable && !resolveWritable({ type: match.type, writable: match.writable })) {
-            throw new ConfigError(`source ${explicitTarget} is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${explicitTarget}" source in your config, or pass --target to a different source.`);
+            throw new ConfigError(`source ${explicitTarget} is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${explicitTarget}" source in your config, or pass ${flag} to a different source.`);
         }
         return adaptConfiguredSource(match);
     }

package/dist/indexer/usage/usage-events.js

@@ -85,7 +85,8 @@ export function countFeedbackSignals(db, entryId) {
  * Count usage events of a given `event_type`.
  *
  * Lifted verbatim from `akm improve` (improve.ts) where the show-event count
- * was hand-rolled inline to drive the zero-feedback fallback warning.
+ * was hand-rolled inline to drive the warning that the retrieval scope matches
+ * only search-retrieved assets.
  */
 export function countUsageEventsByType(db, eventType) {
     return db.prepare("SELECT COUNT(*) AS cnt FROM usage_events WHERE event_type = ?").get(eventType)

package/dist/output/shapes/helpers.js

@@ -86,6 +86,7 @@ export function shapeProposalEntry(entry, detail) {
             "confidence",
             "gateDecision",
             "review",
+            "reviewHistory",
             "retirement",
         ]);
     }
@@ -102,6 +103,7 @@ export function shapeProposalEntry(entry, detail) {
         "gateDecision",
         "payload",
         "review",
+        "reviewHistory",
         "retirement",
         "retiredArchive",
         "promotionSource",
@@ -167,6 +169,11 @@ export function shapeProposalDiffOutput(result, detail) {
         isNew: result.isNew,
         unified: result.unified,
         ...(result.targetPath !== undefined ? { targetPath: result.targetPath } : {}),
+        // A retire proposal (#997): the diff alone is a file leaving, so the pair
+        // verdict and the accept/revert note travel with it at every detail level.
+        ...(result.op !== undefined ? { op: result.op } : {}),
+        ...(result.retirement !== undefined ? { retirement: result.retirement } : {}),
+        ...(result.note !== undefined ? { note: result.note } : {}),
     };
     if (detail === "full") {
         return { schemaVersion: result.schemaVersion, ...base };

package/dist/output/shapes/passthrough.js

@@ -53,6 +53,7 @@ const PASSTHROUGH_COMMANDS = [
     "proposal-accept-batch",
     "proposal-drain",
     "proposal-reject-batch",
+    "proposal-reopen-batch",
     "proposal-revert",
     "registry-add",
     "registry-list",

package/dist/output/shapes/proposal/reopen.js

@@ -0,0 +1,14 @@
+// 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/.
+// Output shape registration for `akm proposal reopen` (#997). One reopened
+// proposal is the same envelope `reject` returns (`ok`, `id`, `ref`, an
+// optional `reason` — here the reopen reason — and the shaped proposal), so it
+// shares that shaper; several are the passthrough `proposal-reopen-batch`.
+import { shapeProposalRejectOutput } from "../helpers.js";
+export const proposalReopenShapes = [
+    {
+        command: "proposal-reopen",
+        handler: (result, detail) => shapeProposalRejectOutput(result, detail),
+    },
+];